DataPower: The XML Management Interface

53
ibm.com/redbooks Redpaper Front cover WebSphere DataPower SOA Appliance: The XML Management Interface Rolf Wittich Appliance Management Protocol (AMP) configuration examples SOAP Configuration Management (SOMA) examples Debugging tips and common errors

Transcript of DataPower: The XML Management Interface

Page 1: DataPower: The XML Management Interface

ibmcomredbooks Redpaper

Front cover

WebSphere DataPower SOA Appliance The XML Management Interface

Rolf Wittich

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

International Technical Support Organization

DataPower The XML Management Interface

September 2008

REDP-4446-00

copy Copyright International Business Machines Corporation 2008 All rights reservedNote to US Government Users Restricted Rights -- Use duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp

First Edition (September 2008)

This edition applies to WebSphere DataPower SOA Appliance Version 371

Note Before using this information and the product it supports read the information in ldquoNoticesrdquo on page v

Contents

Notices vTrademarks vi

Preface viiThe team that wrote this paper viiBecome a published author viiiComments welcome viii

Chapter 1 The Basics 111 Overview of the XML Management Interface 2

111 Appliance Management Protocol (AMP) 2112 SOAP Configuration Management (SOMA) 2113 WebService-Management (WSM) 2114 Web Services Distributed Management (WSDM) 2115 Service Level Monitoring (SLM) 3116 Universal Description Discovery and Integration (UDDI) 3

12 XML Management Interface endpoints 313 Setting up using the WebGUI 314 Setting up by using the Command Line Interface 515 How to send requests to the XML Management Interface 6

Chapter 2 Appliance Management Protocol (AMP) 921 What is AMP 1022 Configuration examples 10

221 Get the domain list of the device 10222 Get device information 11223 Enable (start) an application domain 12224 Disable an application domain 12225 Restart an application domain 13226 Delete an application domain 14227 Reboot the device 14228 Reload the firmware 15229 Upgrade the firmware 15

Chapter 3 SOAP Configuration Management (SOMA) 1731 What is SOMA 1832 Configuration examples 18

321 Flush the document cache 18322 Flush the stylesheet cache 19323 Flush AAA cache 20324 Flush RBM cache 20325 Flush ARP cache 21326 Set the log level in the default or the application domain 21327 Create a backup of the device and the application domains 23328 Restore backup 24329 Copy a file to the device 253210 Delete a file from the device 263211 Create a directory on the device 263212 Remove a directory from the device 27

copy Copyright IBM Corp 2008 All rights reserved iii

3213 Export an object 283214 Import an object 293215 Get status by monitoring the device 30

Chapter 4 Debugging 3341 Enabling internal logging by using the WebGUI 3442 Debugging an invalid request 3443 Common errors 35

431 Malformed content 35432 curl (52) Empty reply from server 35433 Authentication failure 36434 Access denied (from client) 36435 curl (7) couldnt connect to host 37436 Internal error 37

44 Additional help 38

Related publications 39IBM Redbooks 39Online resources 39Locating the code samples on the Web 39How to get Redbooks 40Help from IBM 40

iv DataPower The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 2: DataPower: The XML Management Interface

International Technical Support Organization

DataPower The XML Management Interface

September 2008

REDP-4446-00

copy Copyright International Business Machines Corporation 2008 All rights reservedNote to US Government Users Restricted Rights -- Use duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp

First Edition (September 2008)

This edition applies to WebSphere DataPower SOA Appliance Version 371

Note Before using this information and the product it supports read the information in ldquoNoticesrdquo on page v

Contents

Notices vTrademarks vi

Preface viiThe team that wrote this paper viiBecome a published author viiiComments welcome viii

Chapter 1 The Basics 111 Overview of the XML Management Interface 2

111 Appliance Management Protocol (AMP) 2112 SOAP Configuration Management (SOMA) 2113 WebService-Management (WSM) 2114 Web Services Distributed Management (WSDM) 2115 Service Level Monitoring (SLM) 3116 Universal Description Discovery and Integration (UDDI) 3

12 XML Management Interface endpoints 313 Setting up using the WebGUI 314 Setting up by using the Command Line Interface 515 How to send requests to the XML Management Interface 6

Chapter 2 Appliance Management Protocol (AMP) 921 What is AMP 1022 Configuration examples 10

221 Get the domain list of the device 10222 Get device information 11223 Enable (start) an application domain 12224 Disable an application domain 12225 Restart an application domain 13226 Delete an application domain 14227 Reboot the device 14228 Reload the firmware 15229 Upgrade the firmware 15

Chapter 3 SOAP Configuration Management (SOMA) 1731 What is SOMA 1832 Configuration examples 18

321 Flush the document cache 18322 Flush the stylesheet cache 19323 Flush AAA cache 20324 Flush RBM cache 20325 Flush ARP cache 21326 Set the log level in the default or the application domain 21327 Create a backup of the device and the application domains 23328 Restore backup 24329 Copy a file to the device 253210 Delete a file from the device 263211 Create a directory on the device 263212 Remove a directory from the device 27

copy Copyright IBM Corp 2008 All rights reserved iii

3213 Export an object 283214 Import an object 293215 Get status by monitoring the device 30

Chapter 4 Debugging 3341 Enabling internal logging by using the WebGUI 3442 Debugging an invalid request 3443 Common errors 35

431 Malformed content 35432 curl (52) Empty reply from server 35433 Authentication failure 36434 Access denied (from client) 36435 curl (7) couldnt connect to host 37436 Internal error 37

44 Additional help 38

Related publications 39IBM Redbooks 39Online resources 39Locating the code samples on the Web 39How to get Redbooks 40Help from IBM 40

iv DataPower The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 3: DataPower: The XML Management Interface

copy Copyright International Business Machines Corporation 2008 All rights reservedNote to US Government Users Restricted Rights -- Use duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp

First Edition (September 2008)

This edition applies to WebSphere DataPower SOA Appliance Version 371

Note Before using this information and the product it supports read the information in ldquoNoticesrdquo on page v

Contents

Notices vTrademarks vi

Preface viiThe team that wrote this paper viiBecome a published author viiiComments welcome viii

Chapter 1 The Basics 111 Overview of the XML Management Interface 2

111 Appliance Management Protocol (AMP) 2112 SOAP Configuration Management (SOMA) 2113 WebService-Management (WSM) 2114 Web Services Distributed Management (WSDM) 2115 Service Level Monitoring (SLM) 3116 Universal Description Discovery and Integration (UDDI) 3

12 XML Management Interface endpoints 313 Setting up using the WebGUI 314 Setting up by using the Command Line Interface 515 How to send requests to the XML Management Interface 6

Chapter 2 Appliance Management Protocol (AMP) 921 What is AMP 1022 Configuration examples 10

221 Get the domain list of the device 10222 Get device information 11223 Enable (start) an application domain 12224 Disable an application domain 12225 Restart an application domain 13226 Delete an application domain 14227 Reboot the device 14228 Reload the firmware 15229 Upgrade the firmware 15

Chapter 3 SOAP Configuration Management (SOMA) 1731 What is SOMA 1832 Configuration examples 18

321 Flush the document cache 18322 Flush the stylesheet cache 19323 Flush AAA cache 20324 Flush RBM cache 20325 Flush ARP cache 21326 Set the log level in the default or the application domain 21327 Create a backup of the device and the application domains 23328 Restore backup 24329 Copy a file to the device 253210 Delete a file from the device 263211 Create a directory on the device 263212 Remove a directory from the device 27

copy Copyright IBM Corp 2008 All rights reserved iii

3213 Export an object 283214 Import an object 293215 Get status by monitoring the device 30

Chapter 4 Debugging 3341 Enabling internal logging by using the WebGUI 3442 Debugging an invalid request 3443 Common errors 35

431 Malformed content 35432 curl (52) Empty reply from server 35433 Authentication failure 36434 Access denied (from client) 36435 curl (7) couldnt connect to host 37436 Internal error 37

44 Additional help 38

Related publications 39IBM Redbooks 39Online resources 39Locating the code samples on the Web 39How to get Redbooks 40Help from IBM 40

iv DataPower The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 4: DataPower: The XML Management Interface

Contents

Notices vTrademarks vi

Preface viiThe team that wrote this paper viiBecome a published author viiiComments welcome viii

Chapter 1 The Basics 111 Overview of the XML Management Interface 2

111 Appliance Management Protocol (AMP) 2112 SOAP Configuration Management (SOMA) 2113 WebService-Management (WSM) 2114 Web Services Distributed Management (WSDM) 2115 Service Level Monitoring (SLM) 3116 Universal Description Discovery and Integration (UDDI) 3

12 XML Management Interface endpoints 313 Setting up using the WebGUI 314 Setting up by using the Command Line Interface 515 How to send requests to the XML Management Interface 6

Chapter 2 Appliance Management Protocol (AMP) 921 What is AMP 1022 Configuration examples 10

221 Get the domain list of the device 10222 Get device information 11223 Enable (start) an application domain 12224 Disable an application domain 12225 Restart an application domain 13226 Delete an application domain 14227 Reboot the device 14228 Reload the firmware 15229 Upgrade the firmware 15

Chapter 3 SOAP Configuration Management (SOMA) 1731 What is SOMA 1832 Configuration examples 18

321 Flush the document cache 18322 Flush the stylesheet cache 19323 Flush AAA cache 20324 Flush RBM cache 20325 Flush ARP cache 21326 Set the log level in the default or the application domain 21327 Create a backup of the device and the application domains 23328 Restore backup 24329 Copy a file to the device 253210 Delete a file from the device 263211 Create a directory on the device 263212 Remove a directory from the device 27

copy Copyright IBM Corp 2008 All rights reserved iii

3213 Export an object 283214 Import an object 293215 Get status by monitoring the device 30

Chapter 4 Debugging 3341 Enabling internal logging by using the WebGUI 3442 Debugging an invalid request 3443 Common errors 35

431 Malformed content 35432 curl (52) Empty reply from server 35433 Authentication failure 36434 Access denied (from client) 36435 curl (7) couldnt connect to host 37436 Internal error 37

44 Additional help 38

Related publications 39IBM Redbooks 39Online resources 39Locating the code samples on the Web 39How to get Redbooks 40Help from IBM 40

iv DataPower The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 5: DataPower: The XML Management Interface

3213 Export an object 283214 Import an object 293215 Get status by monitoring the device 30

Chapter 4 Debugging 3341 Enabling internal logging by using the WebGUI 3442 Debugging an invalid request 3443 Common errors 35

431 Malformed content 35432 curl (52) Empty reply from server 35433 Authentication failure 36434 Access denied (from client) 36435 curl (7) couldnt connect to host 37436 Internal error 37

44 Additional help 38

Related publications 39IBM Redbooks 39Online resources 39Locating the code samples on the Web 39How to get Redbooks 40Help from IBM 40

iv DataPower The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 6: DataPower: The XML Management Interface

Notices

This information was developed for products and services offered in the USA

IBM may not offer the products services or features discussed in this document in other countries Consult your local IBM representative for information on the products and services currently available in your area Any reference to an IBM product program or service is not intended to state or imply that only that IBM product program or service may be used Any functionally equivalent product program or service that does not infringe any IBM intellectual property right may be used instead However it is the users responsibility to evaluate and verify the operation of any non-IBM product program or service

IBM may have patents or pending patent applications covering subject matter described in this document The furnishing of this document does not give you any license to these patents You can send license inquiries in writing to IBM Director of Licensing IBM Corporation North Castle Drive Armonk NY 10504-1785 USA

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF NON-INFRINGEMENT MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE Some states do not allow disclaimer of express or implied warranties in certain transactions therefore this statement may not apply to you

This information could include technical inaccuracies or typographical errors Changes are periodically made to the information herein these changes will be incorporated in new editions of the publication IBM may make improvements andor changes in the product(s) andor the program(s) described in this publication at any time without notice

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you

Information concerning non-IBM products was obtained from the suppliers of those products their published announcements or other publicly available sources IBM has not tested those products and cannot confirm the accuracy of performance compatibility or any other claims related to non-IBM products Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products

This information contains examples of data and reports used in daily business operations To illustrate them as completely as possible the examples include the names of individuals companies brands and products All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental

COPYRIGHT LICENSE

This information contains sample application programs in source language which illustrate programming techniques on various operating platforms You may copy modify and distribute these sample programs in any form without payment to IBM for the purposes of developing using marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written These examples have not been thoroughly tested under all conditions IBM therefore cannot guarantee or imply reliability serviceability or function of these programs

copy Copyright IBM Corp 2008 All rights reserved v

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 7: DataPower: The XML Management Interface

Trademarks

IBM the IBM logo and ibmcom are trademarks or registered trademarks of International Business Machines Corporation in the United States other countries or both These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (reg or trade) indicating US registered or common law trademarks owned by IBM at the time this information was published Such trademarks may also be registered or common law trademarks in other countries A current list of IBM trademarks is available on the Web at httpwwwibmcomlegalcopytradeshtml

The following terms are trademarks of the International Business Machines Corporation in the United States other countries or both

DataPower deviceregDataPowerreg

IBMregRedbooksreg

Redbooks (logo) regWebSpherereg

The following terms are trademarks of other companies

Win32 Windows and the Windows logo are trademarks of Microsoft Corporation in the United States other countries or both

Linux is a trademark of Linus Torvalds in the United States other countries or both

Other company product or service names may be trademarks or service marks of others

vi DataPower The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 8: DataPower: The XML Management Interface

Preface

The XML Management Interface is the third way to configure and administer the WebSpherereg DataPowerreg SOA Appliance The other two are the WebGUI and the CLI

The DataPower devicereg can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Chapter 1 explains the different flavors of the XML Management Interface (AMP SOAP Configuration Management SOAP Configuration Management v2004 WSM WSDM UDDI SLM) The chapter also describes how to enable and configure the XML Management Interface by using the WebGUI how to activate it using the CLI and how to send the SOAP-Requests to the device

Chapter 2 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the Appliance Management Protocol (AMP) service

Chapter 3 shows the most common requests that can be sent to the XML Management Interface of the DataPower device focusing on the SOAP Configuration Management service

Chapter 4 explains ways to debug your requests and shows the most common mistakes that are made

IBMreg WebSphere DataPower SOA Appliances represent an important element in the IBM approach to Service Oriented Architecture (SOA) IBM SOA appliances are purpose-built easy-to-deploy network devices that simplify help secure and accelerate your XML and Web services deployments while extending your SOA infrastructure This Redpaper assumes familiarity with the general use of DataPower For more information see ldquoRelated publicationsrdquo on page 39 or visit the following Web page

httpwwwibmcomsoftwareintegrationdatapowerindexhtml

The team that wrote this paper

Rolf Wittich is a Support Engineer and IBM Certified Solution Developer for DataPower within the IBM WebSphere DataPower Customer Support He is part of the worldwide DataPower Level 2 Support team and located in Boumlblingen Germany Before joining IBM he worked for the Deutsche Telekom Customer Support He has broad knowledge in communications and networking technologies as well as network-security

copy Copyright IBM Corp 2008 All rights reserved vii

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 9: DataPower: The XML Management Interface

A special thanks to the following people for their contributions

Mike Ebbers IBM International Technical Support Organization Poughkeepsie USA

Robert Bunn IBM Teamlead Level 2 Support for DataPower Raleigh USA

Holger Reinhardt IBM Consumability Architect for DataPower Boumlblingen Germany

Robin Rouse IBM Manager Level 2 Support for DataPower Cambridge USA

Stefan Schwarz IBM Level 2 Support Engineer for WID Boumlblingen Germany

Hermann Stamm-Wilbrandt IBM DataPower Development Boumlblingen Germany

Ben Wen IBM Product Management for DataPower Cambridge USA

Trey Williamson IBM Level 2 Support Engineer for DataPower Raleigh USA

Paul Wilson IBM Level 2 Support Engineer for DataPower Cambridge USA

Become a published author

Join us for a two- to six-week residency program Help write a book dealing with specific products or solutions while getting hands-on experience with leading-edge technologies You will have the opportunity to team with IBM technical professionals Business Partners and Clients

Your efforts will help increase product acceptance and customer satisfaction As a bonus you will develop a network of contacts in IBM development labs and increase your productivity and marketability

Find out more about the residency program browse the residency index and apply online at

ibmcomredbooksresidencieshtml

Comments welcome

Your comments are important to us

We want our papers to be as helpful as possible Send us your comments about this paper or other IBM Redbooksreg in one of the following ways

Use the online Contact us review Redbooks form found at

ibmcomredbooks

Send your comments in an e-mail to

redbooksusibmcom

Mail your comments to

IBM Corporation International Technical Support OrganizationDept HYTD Mail Station P0992455 South RoadPoughkeepsie NY 12601-5400

viii DataPower The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 10: DataPower: The XML Management Interface

Chapter 1 The Basics

The XML Management Interface of the DataPower appliance can be set up for different endpoints

Appliance Management Protocol (AMP)

SOAP Configuration Management (SOMA) and SOAP Configuration Management v2004 an established version of the current SOAP Configuration Management

Web Service Management (WS-Management or WSM)

Web Services Distributed Management (WSDM)

Service level monitoring (SLM)

Universal Description Discovery and Integration (UDDI)

This paper focuses on the AMP and SOAP Configuration Management endpoints

1

copy Copyright IBM Corp 2008 All rights reserved 1

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 11: DataPower: The XML Management Interface

11 Overview of the XML Management Interface

Although this paper focuses on AMP and SOAP (SOMA) this section also describes WSM WSDM SLM UDDI and their URIs

111 Appliance Management Protocol (AMP)

When setting up the Appliance Management Protocol (AMP) endpoint on the XML Management Interface a multi-box management for automated administration processes can be implemented The URI for the AMP endpoint is

servicemgmtamp10

112 SOAP Configuration Management (SOMA)

By using the implemented SOAP Management the device can be administered using SOAP XML requests and responses As mentioned previously the device offers a legacy version of the SOAP Interface SOAP v2004 This version is no longer updated and should only be used for earlier applications The URI for the current version is

servicemgmtcurrent

The URI for SOAP v2004 is

servicemgmt2004

For more information refer to the SOAP Interface in the WebGUI Guide located at

httpwww-1ibmcomsupportdocviewwssrs=2362ampuid=swg24014405

113 WebService-Management (WSM)

Configuring WebService-Management (WSM) on the XML Management Interface exposes management status data using WS-Management semantics The URI for the WSM service is

servicews-management

114 Web Services Distributed Management (WSDM)

Enabling the Web Services Distributed Management (WSDM) endpoint handler displays management status data using WSDM semantics It also supports collection and reporting of WSDM statistics for Web Service Proxy (WS Proxy) hosted Web services The URI for the WSDM service is

servicewsdm-10

For more information about this service refer to the WSDM Interface in the WebGUI Guide

Note The examples shown in this Redpaper use SOAP Configuration Management not SOAP Configuration Management (v2004) SOAP Configuration Management (v2004) has stricter rules and therefore some of the examples shown in this paper will not work

2 DataPower The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 12: DataPower: The XML Management Interface

115 Service Level Monitoring (SLM)

Another multi-box management option that comes with the DataPower XML Management Interface is Service Level Monitoring SLM is a proprietary protocol for exchanging real time transaction monitoring and statistics The URI for addressing the SLM endpoint is

serviceslmdatashare10

The SLM protocol is used to communicate SLM data between appliances and is not a public Web service

116 Universal Description Discovery and Integration (UDDI)

If the Universal Description Discovery and Integration (UDDI) subscription is enabled on the XML Management Interface the device displays a UDDI subscription listener Web service This service endpoint must be configured in the UDDI registry as the subscriptions service endpoint Any number of subscriptions may use this endpoint This endpoint processes subscription updates for all domains The URI for the UDDI subscription endpoint is

serviceuddi-subscription

12 XML Management Interface endpoints

The endpoints in the XML Management Interface their URIs and how they are used are listed in Table 1-1

Table 1-1 XML Management Interface endpoints

13 Setting up using the WebGUI

To enable the XML Management Interface of your DataPower device

1 Using an administrator account log in to the default domain on your DataPower device

Endpoint URI Usage

SOAP Configuration Management

servicemgmtcurrent Precede AMP and could be affected by differences in subsequent firmware versions Despite of this it allows easy manipulation of custom configuration and provides simple yet flexible automation meansIt has a much finer granularity than AMP

SOMA v2004 servicemgmt2004 Legacy version of SOMA Not longer updated Supported for backward compatibility

WSM servicews-management WS-Management provides the possibility to access and exchange management information

WSDM servicewsdm-10 WSDM is a standard to monitor the status of other services

AMP servicemgmtamp10 AMP was developed to address several shortcomings of the existing SOMA interface It is firmware version independent and thereby provides a generalized way of managing the appliance

SLM serviceslmdatashare10 SLM offers the possibility to define monitor and improve services

UDDI serviceuddi-subscription UDDI is a platform-independent registry to publish service listings and define how services interact with each other

Chapter 1 The Basics 3

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 13: DataPower: The XML Management Interface

2 From the navigation bar choose Network rarr Management rarr XML Management Interface A configuration window opens as shown in Figure 1-1

Figure 1-1 XML Management Interface configuration window

3 Set the Local IP Address or use an alias instead

4 Set the Port Number on which you want the XML Management Interface to run

5 Set up an Access Control List (ACL) to prevent unauthorized access to your DataPower XML Management Interface

To define an ACL

a Click the + (plus sign) button

The Access Control List configuration window opens to the Main panel as shown in Figure 1-2 on page 5

4 DataPower The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 14: DataPower: The XML Management Interface

Figure 1-2 Access Control List configuration window

b Enter an ACL name in the Name field For example enter MyACL

c Set the Admin State to enabled

d Click Entry in the navigation bar at the top

e Set up your ACL to allow or deny specific IP-Address-Ranges

The IP address format must be in slash notation for example 123424 if your subnet mask is 2552552550 or 32 for a single client

By allowing one IP address or subnet all other subnets and IP addresses will be denied

6 Click Save

The entry now appears in the Entries-List

7 Repeat the steps until the ACL is completed

The Enabled Services section allows controlling of the various services running on the XML Management Interface This Redpaper focuses on the SOAP Configuration Management and the Appliance Management Protocol (AMP) endpoint

8 Activate the check boxes for SOAP Configuration Management and AMP endpoint

9 Apply your changes

10Save your configuration

14 Setting up by using the Command Line Interface

To enable the XML Management Interface of your DataPower device use the following CLI commands

Xi50 configure terminalXi50(config) xml-mgmt

Important Never activate the check box Enable any () SOAP Management URI Activating it could lead to problems using SOAP Management (SOMA) because any URI is accepted by the device What can happen is that the device uses the SOAP v2004 specifications instead of the current SOAP Management implementation which might cause trouble with the requests sent to the box For example they could be rejected although they are valid

Chapter 1 The Basics 5

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 15: DataPower: The XML Management Interface

Xi50(config xml-mgmt) local-address XXXXXi50(config xml-mgmt) port XXXXXi50(config xml-mgmt) mode amp+soma Xi50(config xml-mgmt) admin-state enabledXi50(config xml-mgmt) exitXi50(config) write memoryOverwrite previously saved configuration [yn] yes

Figure 1-3 shows an example of using the CLI commands

Figure 1-3 Setting up the XML Management Interface by using the CLI

To enable the other services on the XML Management Interface add any of the following abbreviations to the mode command by prefacing each with a + (plus sign)

any Configures the XML Management Interface to listen on any URIslm Configures the XML Management Interface for Service Level Monitoringuddi Enables the UDDI-Subscription on the XML Management Interfacev2004 Configures the XML Management Interface using the earlier version of SOMAwsdm Enables Web Service Distributed Management wsm Enables WebService Management

For example to enable all services use the following CLI command

Mode amp+soma+any+slm+uddi-subscription+v2004+wsdm+wsm

15 How to send requests to the XML Management Interface

After the XML Management Interface is configured and is up and running you can send your request by using the command line tool curl

In Windowsreg you can use Cygwin which is a freeware Linuxreg-like environment for Windows You can download it from the official Web site

httpcygwincomsetupexe

A production system would likely use another XML or SOAP client However curl also has a native Win32reg version

6 DataPower The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 16: DataPower: The XML Management Interface

In this Redpaper the curl command is used to address the management endpoint of the XML Management Interface

The following example shows a request curl command with options

curl ndashk ndashu userpassword ndashd myRequestFilexml httpsDataPowerIPPortEndpointURI

Options for the curl command are

k Allows connections to SSL sites without cert

u Specifies the user and password

d Indicates HTTP post data

Specifies the file that is sent to the XML Management Interface followed by the address of the DataPower device the port the XML Management is running on and the Endpoint URI explained in section 11 ldquoOverview of the XML Management Interfacerdquo on page 2

Figure 1-4 shows an example of entering the command

Figure 1-4 Sending a curl request

Note Note that the XML Management must be called using HTTPS (not HTTP) Make sure the final S is on HTTPS

Chapter 1 The Basics 7

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 17: DataPower: The XML Management Interface

8 DataPower The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 18: DataPower: The XML Management Interface

Chapter 2 Appliance Management Protocol (AMP)

This chapter describes the Appliance Management Protocol (AMP) and provides examples of commands to administer your DataPower appliance

2

copy Copyright IBM Corp 2008 All rights reserved 9

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 19: DataPower: The XML Management Interface

21 What is AMP

The Appliance Management Protocol (AMP) is a series of commands that were developed to address several shortcomings of the existing SOMA interface The structure is simple and should be easy to understand It is independent of a firmware version and thereby provides a generalized way of managing the appliance

The Web Service Definition Language (WSDL) and schema files with all operations and actions that can be performed with AMP are stored on the device Although this Redpaper provides several examples to view additional file examples select

Control Panel rarr File Management rarr Store

In that location the example files to look at are

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

22 Configuration examples

Send AMP requests to a specific address such as

httpsDataPowerIPPortservicemgmtamp10

The examples in this section show how easy the structure is and how simple the AMP requests are The AMP request is embedded in a SOAP message which is sent to the DataPower device by the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

All samples shown in this Redpaper can also be found in either of the following locations

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

221 Get the domain list of the device

The response to the request is a list of all application domains on your device

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

10 DataPower The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 20: DataPower: The XML Management Interface

ltdpGetDomainListRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdomainlistxml httpsDataPowerIPPortservicemgmtamp10

ResponseltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDomainListResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDomaingtDomain1ltampDomaingtltampDomaingtDomain2ltampDomaingtltampDomaingtdefaultltampDomaingtltampDomaingtDomain3ltampDomaingtltampDomaingtDomain4ltampDomaingt

ltampGetDomainListResponsegtltenvBodygt

ltenvEnvelopegt

222 Get device information

The response to the request shows the device name the serial number the device ID (9003) the device type (XA35 XS40 XI50) the firmware version any failures and the license set of your DataPower device

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpGetDeviceInfoRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gtltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_getdeviceinfoxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampGetDeviceInfoResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampDeviceNamegtDataPower XI50ltampDeviceNamegtltampDeviceSerialNogtXXXXXXXltampDeviceSerialNogtltampDeviceIDgt9003-XI50-03ltampDeviceIDgtltampDeviceTypegtXI50ltampDeviceTypegt

Chapter 2 Appliance Management Protocol (AMP) 11

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 21: DataPower: The XML Management Interface

ltampFirmwareVersiongtXI5036025ltampFirmwareVersiongtltampFailureDetectedgtfalseltampFailureDetectedgtltampManagementInterface type=web-mgmtgt9090ltampManagementInterfacegtltampDeviceFeaturegtMQltampDeviceFeaturegtltampDeviceFeaturegtTAMltampDeviceFeaturegtltampDeviceFeaturegtDataGlueltampDeviceFeaturegtltampDeviceFeaturegtJAXP-APIltampDeviceFeaturegtltampDeviceFeaturegtPKCS7-SMIMEltampDeviceFeaturegtltampDeviceFeaturegtSQL-ODBCltampDeviceFeaturegtltampDeviceFeaturegtTibco-EMSltampDeviceFeaturegtltampDeviceFeaturegtWebSphere-JMSltampDeviceFeaturegt

ltampGetDeviceInfoResponsegtltenvBodygt

ltenvEnvelopegt

223 Enable (start) an application domain

This request sets the admin state of the application domain myDomain to enabled The ampStatus OK in the response indicates that the request was performed successfully and your domain is now enabled

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_startdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStartDomainResponsegtltenvBodygt

ltenvEnvelopegt

224 Disable an application domain

The application domain myDomain is set to disabled

12 DataPower The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 22: DataPower: The XML Management Interface

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpStopDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpStopDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_stopdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampStopDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampStopDomainResponsegtltenvBodygt

ltenvEnvelopegt

225 Restart an application domain

The application domain myDomain is restarted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRestartDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpRestartDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_restartdomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRestartDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

Chapter 2 Appliance Management Protocol (AMP) 13

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 23: DataPower: The XML Management Interface

ltampRestartDomainResponsegtltenvBodygt

ltenvEnvelopegt

226 Delete an application domain

The application domain myDomain is deleted

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpDeleteDomainRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpDomaingtmyDomainltdpDomaingtltdpDeleteDomainRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_deletedomainxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampDeleteDomainResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampDeleteDomainResponsegtltenvBodygt

ltenvEnvelopegt

227 Reboot the device

The DataPower device reboots which might take several moments

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtrebootltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_rebootxml httpsDataPowerIPPortservicemgmtamp10

14 DataPower The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 24: DataPower: The XML Management Interface

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

228 Reload the firmware

The firmware is reloaded

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdpRebootRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpModegtreloadltdpModegtltdpRebootRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl commandcurl ndashk ndashu userpassword ndashd AMP_reloadxml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampRebootResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampRebootResponsegtltenvBodygt

ltenvEnvelopegt

229 Upgrade the firmware

The Base64_Encoded_Firmware_Image must be replaced by the base64 encoded file content Because this can be more than 700000 lines of code we decided to replace it Processing this request might take several seconds The device rebooted after the image was installed

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

Chapter 2 Appliance Management Protocol (AMP) 15

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 25: DataPower: The XML Management Interface

ltdpSetFirmwareRequest xmlnsdp=httpwwwdatapowercomschemasappliancemanagement10gt

ltdpFirmwaregtBase64_Encoded_Firmware_ImageltdpFirmwaregtltdpSetFirmwareRequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Curl command curl ndashk ndashu userpassword ndashd AMP_setfirmwarexml httpsDataPowerIPPortservicemgmtamp10

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltampSetFirmwareResponse

xmlnsamp=httpwwwdatapowercomschemasappliancemanagement10gtltampStatusgtokltampStatusgt

ltampSetFirmwareResponsegtltenvBodygt

ltenvEnvelopegt

16 DataPower The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 26: DataPower: The XML Management Interface

Chapter 3 SOAP Configuration Management (SOMA)

SOMA is the abbreviation for SOAP Configuration Management It provides commands to administer the DataPower appliance SOMA was written before AMP and can be affected by differences in subsequent firmware versions However SOMA provides easy manipulation of custom configurations and simple flexible automation

3

copy Copyright IBM Corp 2008 All rights reserved 17

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 27: DataPower: The XML Management Interface

31 What is SOMA

SOMA has a much finer granularity than AMP The WSDL and schema files with all operations and actions that can be performed with SOMA are stored on the device

To find those files select

Control Panel rarr File Management rarr Store

In the store directory of the DataPower Appliance the files are

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

32 Configuration examples

Send SOMA requests to a certain address such as

httpsDataPowerIPPortservicemgmtcurrent

The examples in this section show how to run automated processes The SOMA request is embedded in a SOAP message that is sent to the DataPower device by using the curl command Each example shows the source code of the SOAP message the curl command to send to the DataPower device and the response from DataPower

The structure of each example is

Request Curl command Response

Every SOAP message consists of a request that has an operation (do-action do-import for example) and the actual action to execute If an operation has optional attributes they are also described in this section

321 Flush the document cache

The ltdpresultgt element in the response shows that the operation was performed successfully and the cache was flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=someBank-Sample xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushDocumentCachegt ltXMLManagergtsomeBankXMLltXMLManagergt ltFlushDocumentCachegt ltdpdo-actiongt

18 DataPower The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 28: DataPower: The XML Management Interface

ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushdocumentcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T163105+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

322 Flush the stylesheet cache

The stylesheet cache is flushed

Requestltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushStylesheetCachegt ltXMLManagergtdefaultltXMLManagergt ltFlushStylesheetCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushstylesheetcachexml httpsDataPowerIPPortservicemgmtcurrent

Responseltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164158+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Chapter 3 SOAP Configuration Management (SOMA) 19

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 29: DataPower: The XML Management Interface

323 Flush AAA cache

The ltFlushAAACachegt element requires the AAA ltPolicyNamegt as the child element AAA_Auth is the name we chose for the AAA Policy specified in an XML firewall in the default domain

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushAAACachegt ltPolicyNamegtAAA_AuthltPolicyNamegt ltFlushAAACachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandcurl -k -u userpassword -d soma_flushaaacachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164330+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

324 Flush RBM cache

This flushes role based management (RBM) configuration mode cache

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushRBMCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

20 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 30: DataPower: The XML Management Interface

Curl command curl -k -u userpassword -d soma_flushrbmcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T164856+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

325 Flush ARP cache

This flushes Address Resolution Protocol (ARP) cache With ARP you can get a hosts hardware address when you only know the IP address

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltFlushArpCachegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_flusharpcachexml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-12T165256+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

326 Set the log level in the default or the application domain

This is request to change the log level of the default domain or the application domain To set the log level in the default domain leave the request as it is If you want to change the log

Chapter 3 SOAP Configuration Management (SOMA) 21

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 31: DataPower: The XML Management Interface

level in an application domain add the domain=myDomain attribute to the ltdprequestgt element

In the request the ltLogLevelgt element can be set to one of the following values

emerg emergency log level

alert alert log level

critic critical log level

error error log level

warn warning log level

notice notice log level

info information log level

debug debug log level

Request to change the log level of the default domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Request to change the log level of the myDomain application domainltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=myDomain xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltSetLogLevelgt ltLogLevelgtemergltLogLevelgt ltSetLogLevelgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl commandscurl -k -u userpassword -d soma_logleveldefaultxml httpsDataPowerIPPortservicemgmtcurrent

curl -k -u userpassword -d soma_loglevelapplicationdomainxml httpsDataPowerIPPortservicemgmtcurrent

22 DataPower The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 32: DataPower: The XML Management Interface

Responsesltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104016+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T104221+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

327 Create a backup of the device and the application domains

To perform a backup of the entire system use ltdpdomain name=all-domainsgt Refer to Table 3-1 for a list of do-backup attributes

Requestltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-backup format=ZIPgt

ltdpdomain name=defaultgtlt-- enter all the application domains you want to be included in your domain backup here only the default domain will be included in the backup for a entire system backup use ltdpdomain name=rdquoall-domainsrdquogt--gt

ltdpdo-backupgtltdprequestgt

ltsoapenvBodygtltsoapenvEnvelopegt

Table 3-1 Attributes of the do-backup function

Curl commandcurl -k -u userpassword -d soma_createbackupxml httpsDataPowerIPPortservicemgmtcurrent gt backupxml

do-backup operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

persisted truefalse

If set to true only the domains with saved configurations will be included in the backup

Chapter 3 SOAP Configuration Management (SOMA) 23

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 33: DataPower: The XML Management Interface

Response The response is shown in the backup file created

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T123520+0100ltdptimestampgtltdpfilegtbase64 encoded file contentltdpfilegt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

328 Restore backup

The following do-restore operation shows a Base64_Encoded_File placeholder value This means that the complete file must be encoded in base64 and included in the ltdpinput-filegt element Because this file can be several thousand lines it was simply replaced by this placeholder Refer to Table 3-2 for a list of do-restore attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpdo-restore source-type=ZIPgt

ltdpinput-filegtBase64_Encoded_Fileltdpinput-filegtltdpdomain name=defaultgtlt-- enter all the domains you want to be

restored --gt

ltdpdo-restoregtltdpdo-actiongt

ltSaveConfiggtltdpdo-actiongt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-2 Attributes of the do-restore function

do-restore operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

24 DataPower The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 34: DataPower: The XML Management Interface

Curl command curl -k -u userpassword -d soma_restorebackupxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T150859+0100ltdptimestampgtltdpimportgt

ltimport-results domain=defaultgtltexport-detailsgt

[]ltexport-detailsgt

ltimport-resultsgtltdpimport

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

329 Copy a file to the device

Refer to Table 3-3 for a list of set-file attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagementgtltdpset-file name=localTestfilegt

Base64_encoded_Fileltdpset-filegt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-3 Attribute of the set-file function

Curl command curl -k -u userpassword -d soma_copyfilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

set-file operation Value Description

name Image AnyStringLocalAnyStringTemporaryAnyString

Specifies the location of where to upload the file on the DataPower filesystem and how to name it

Chapter 3 SOAP Configuration Management (SOMA) 25

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 35: DataPower: The XML Management Interface

ltdptimestampgt2008-03-13T151307+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3210 Delete a file from the device

Use this request to delete a file from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltDeleteFilegt

ltFilegtlocalTestfileltFilegt ltDeleteFilegt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_deletefilexml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T151534+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3211 Create a directory on the device

Use this request to create a directory on the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltCreateDirgt

26 DataPower The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 36: DataPower: The XML Management Interface

ltDirgtlocaltestdirectoryltDirgt ltCreateDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_createdirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response xml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161723+0100ltdptimestampgtltdpresultgtOKltdpresultgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3212 Remove a directory from the device

Use this request to remove a directory from the device

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpdo-actiongt ltRemoveDirgt

ltDirgtlocaltestdirectoryltDirgt ltRemoveDirgt ltdpdo-actiongt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_removedirectoryxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-13T161942+0100ltdptimestampgtltdpresultgtOKltdpresultgt

Chapter 3 SOAP Configuration Management (SOMA) 27

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 37: DataPower: The XML Management Interface

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3213 Export an object

Table 3-4 lists the do-export attributes Table 3-5 lists the object attributes

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-export format=ZIP all-files=truegtltdpobject name=SomeObject class=XMLFirewallService

ref-objects=true ref-files=truegtltdpdo-exportgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-4 Attributes of the do-export function

Table 3-5 Attributes of the object element

To export all objects of all classes set the following attributes in the ltdpobjectgt element

name = ldquoall-objectsrdquo Indicates all objects of the specified class

class = ldquoall-classesrdquo Specifies all classes

Curl command curl -k -u userpassword -d soma_objectbasedexportxml httpsDataPowerIPPortservicemgmtcurrent gt export txt

do-export operation Value Description

format ZIPXML

Specifies the export format of the backup file either ZIP or XML

all-files truefalse

If set to true all files of the specified domain are exported

persisted truefalse

If set to true only the domains with saved configurations are included in the backup

object element Description

name Specifies the name of particular object to export

class Specifies the class of the object

28 DataPower The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 38: DataPower: The XML Management Interface

Response The exporttxt file contains the contents of the base 64-encoded file (in the ltdpfilegt element immediately after the timestamp)

Total Received Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 425k 0 425k 0 0 219k 0 ------ 00001 ------ 491k

3214 Import an object

This imports the object from the example shown in section 3213 ldquoExport an objectrdquo on page 28 Refer to the do-import attributes in Table 3-6

Request ltxml version=10 encoding=UTF-8gtltsoapenvEnvelope xmlnssoapenv=httpschemasxmlsoaporgsoapenvelopegtltsoapenvBodygt

ltdprequest xmlnsdp=httpwwwdatapowercomschemasmanagement domain=myDomaingt

ltdpdo-import source-type=ZIP overwrite-objects=true overwrite-files=truegt

ltdpinput-filegtBase_64_encoded_Exportltdpinput-filegtltdpobject name=SomeObject class=XMLFirewallService

overwrite=truegtltdpdo-importgt

ltdprequestgtltsoapenvBodygtltsoapenvEnvelopegt

Table 3-6 Attributes of the do-import function

Curl command curl -k -u userpassword -d soma_objectbasedimortxml httpsDataPowerIPPortservicemgmtcurrent

Response ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-18T174822+0100ltdptimestampgt

do-import operation Value Description

source-type ZIPXML

Specifies the source type of the export to be imported

dry-run truefalse

If set to true the device performs a dry run of the command

overwrite-files truefalse

If set to true existing files are overwritten

overwrite-objects truefalse

If set to true existing objects are overwritten

Chapter 3 SOAP Configuration Management (SOMA) 29

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 39: DataPower: The XML Management Interface

ltdpimportgtltimport-results domain=myDomaingt

ltexport-detailsgtltdescriptiongtExported Configuration ltdescriptiongtltusergtadminltusergtltdomaingtmyDomainltdomaingtltcommentgtltproduct-idgt9003-XI50-03ltproduct-idgtltproductgtXI50ltproductgtltmodelgtDataPower XI50ltmodelgt[]ltcfg-result class=XMLFirewallService name=SomeObject

status=SUCCESSgtltexport-detailsgt

ltimport-resultsgtltdpimportgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

3215 Get status by monitoring the device

By changing the class attribute of the ltdpget-statusgt element you can monitor different values of the DataPower device This example shows the CPUUsage value For a list of other values see ldquoValues of the class attributerdquo on page 31

Request ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt ltenvBodygt ltdprequest domain=default xmlnsdp=httpwwwdatapowercomschemasmanagementgt ltdpget-status class=CPUUsagegt ltdprequestgt ltenvBodygtltenvEnvelopegt

Curl command curl -k -u userpassword -d soma_getstatusxml httpsDataPowerIPPortservicemgmtcurrent

Response ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdptimestampgt2008-03-19T173217+0100ltdptimestampgtltdpstatusgt

ltCPUUsage xmlnsenv=httpwwww3org200305soap-envelopegtlttenSecondsgt5lttenSecondsgtltoneMinutegt3ltoneMinutegtlttenMinutesgt6lttenMinutesgtltoneHourgt6ltoneHourgtltoneDaygt6ltoneDaygt

30 DataPower The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 40: DataPower: The XML Management Interface

ltCPUUsagegtltdpstatusgt

ltdpresponsegtltenvBodygt

ltenvEnvelopegt

Values of the class attributeBy changing the class attribute you can monitor the following values or status of the DataPower device

A ActiveUsers ARPStatus

C ConnectionsAccepted CPUUsage CryptoEngineStatus

D DateTimeStatus DNSCacheHostStatus DNSNameServerStatus DNSSearchDomainStatus DNSStaticHostStatus DocumentCachingSummary DocumentStatus DocumentStatusSimpleIndex DomainStatus DynamicQueueManager

E EnvironmentalFanSensors EnvironmentalSensors EthernetInterfaceStatus

F FilePollerStatus FilesystemStatus FirmwareStatus FirmwareVersion

H HSMKeyStatus HTTPConnections HTTPConnectionsCreated HTTPConnectionsDestroyed HTTPConnectionsOffered HTTPConnectionsRequested HTTPConnectionsReturned HTTPConnectionsReused HTTPMeanTransactionTime HTTPTransactions

L LibraryVersion LicenseStatus LoadBalancerStatus LogTargetStatus

M MemoryStatus MessageCountFilters MessageCounts MessageDurationFilters MessageDurations MessageSources MQQMstatus MQStatus

N NFSMountStatus NTPRefreshStatus

O ObjectStatus

P PortStatus

R ReceiveKbpsThroughput ReceivePacketThroughput RoutingStatus

S ServicesStatus SLMPeeringStatus SLMSummaryStatus SNMPStatus SSHTrustedHostStatus StandbyStatus StylesheetCachingSummary StylesheetExecutions StylesheetExecutionsSimpleIndex StylesheetMeanExecutionTime StylesheetMeanExecutionTimeSimpleIndex StylesheetProfiles StylesheetProfilesSimpleIndex StylesheetStatus StylesheetStatusSimpleIndex SystemUsage

T TCPSummary TCPTable TibcoEMSStatus TransmitKbpsThroughput TransmitPacketThroughput

U UDDISubscriptionKeyStatusSimpleIndex UDDISubscriptionServiceStatusSimpleIndex UDDISubscriptionStatusSimpleIndex

V Version

W WebAppFwAccepted WebAppFwRejected WebSphereJMSStatus WSMAgentSpoolers WSMAgentStatus WSOperationMetrics WSOperationsStatus WSRRSubscriptionServiceStatus WSRRSubscriptionStatus WSWSDLStatus WSWSDLStatusSimpleIndex

Some of the values show the output only if statistics are enabled on your DataPower device To enable statistics from the WebGUI select

Objects rarr System rarr Statistic settings

Chapter 3 SOAP Configuration Management (SOMA) 31

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 41: DataPower: The XML Management Interface

32 DataPower The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 42: DataPower: The XML Management Interface

THIS PAGE INTENTIONALLY LEFT BLANK

sponsorship promotion

the above is a paid promotion it does not constitute an endorsement of any of the above companys products services or websites by ibm nor does it reflect the opinion of ibm ibm management shareholders or officers ibm disclaims any and all warrantees for

goods or services received through or promoted by the above company

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 43: DataPower: The XML Management Interface

Chapter 4 Debugging

If a request is not valid the DataPower device does not provide detailed information in the response This is by design because showing details to any client sending a request to the XML Management Interface would be a security exposure This is why in most cases the response indicates simply Internal Error The only way to debug failing requests is to enable internal logging on the device

This chapter shows how to enable internal logging and how to debug problems It provides solutions to common mistakes during the use of the XML Management Interface

4

copy Copyright IBM Corp 2008 All rights reserved 33

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 44: DataPower: The XML Management Interface

41 Enabling internal logging by using the WebGUI

To enable internal logging

1 Using an administrator ID log in into the default domain of your DataPower device

2 From the Control Panel click the Troubleshooting Icon

3 In the Logging section shown in Figure 4-1

a Set the Log Level to debug

b Set Enable Internal Logging to on

c Click the Set Log Level button

4 Save your configuration

Figure 4-1 Setting the log level

42 Debugging an invalid request

At the beginning of the chapter we mentioned that for security reasons the DataPower device provides little information Most of the time the response indicates Internal Error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

If you receive a response like this to your request check the default log for more detailed information The default log only shows entries of the XML Management Interface when internal logging is enabled Steps for enabling internal logging are listed in section 41 ldquoEnabling internal logging by using the WebGUIrdquo on page 34 The log shows errors of the WebGUI category with messages from an XML firewall called xml-mgmt The errors look similar to the error shown in Figure 4-2 on page 35

The message clearly states where the error is which is in the element ltFlushAAACachegt in the do-action of the request It also states what was expected By comparing the list of expected elements to the element used in the request you can determine that a typographical error exists in the ltFlushAAACachegt element of the request

34 DataPower The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 45: DataPower: The XML Management Interface

Figure 4-2 XML firewall message

When you debug check the following items

Check your curl command

Check your request XML file

Check the default log for any entries of the XML Management Interface

43 Common errors

As you can imagine there are probably as many errors as grains of sand at the beach To highlight the most common mistakes this section provides examples of errors we encountered

431 Malformed content

The following error response indicates malformed content which means the request was not well-formed

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtMalformed content (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log lists a message similar to the following message

xmlfirewall (xml-mgmt) mismatched tag expected dpdo-action at line 1

Check the syntax of the request file It could be missing an angle bracket (lt or gt) or a closing tag

432 curl (52) Empty reply from server

When sending a curl request to the DataPower device using HTTP instead of HTTPS the following error is in the response

curl (52) Empty reply from server

Chapter 4 Debugging 35

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 46: DataPower: The XML Management Interface

The log lists the following error message

Check the syntax of your curl request The XML Management Interface uses HTTPS for communication not HTTP

433 Authentication failure

You might receive the following authentication failure response from your DataPower device

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltdpresponse xmlnsdp=httpwwwdatapowercomschemasmanagementgt

ltdpresultgtAuthentication failureltdpresultgtltdpresponsegt

ltenvBodygtltenvEnvelopegt

The log lists the following error message

xmlfirewall (map) RBM Authetication failed - Access Denied

This states that the RBM Authentication failed with the user credentials that were sent to the device

Check the username and password you specified in the curl request

434 Access denied (from client)

DataPower might send the following response to a curl command

ltxml version=10 encoding=UTF-8gtltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegt

ltenvBodygtltenvFaultgt

ltfaultcodegtenvClientltfaultcodegtltfaultstringgtAccess Denied (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

The log shows the following error message

xmlfirewall (xml-mgmt) Unknown xml-mgmt service URI lsquoservicesmgmtcurrent

This indicates an incorrect URI The correct URI is servicemgmtcurrent (no s on the word service) rather than servicesmgmtcurrent as shown

Check the URI used in your curl command

36 DataPower The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 47: DataPower: The XML Management Interface

435 curl (7) couldnt connect to host

The response might indicate the following message

curl (7) couldnt connect to host

The log lists the following this error message

Check the port number you sent the request to Addressing the request to the correct XML Management Interface port can solve this issue

436 Internal error

The following response shows an internal error

ltenvEnvelope xmlnsenv=httpschemasxmlsoaporgsoapenvelopegtltenvBodygt

ltenvFaultgtltfaultcodegtenvClientltfaultcodegtltfaultstringgtInternal Error (from client)ltfaultstringgt

ltenvFaultgtltenvBodygt

ltenvEnvelopegt

Because it can be caused by several situations the only way to debug is to check the log for details about the error

Error from an invalid elementThis internal error was caused by an invalid element in the request As shown in Figure 4-3 the log message indicates where the error is (in the element ltFlushAAACashegt in the do-action of the request) and what was expected

Figure 4-3 Error message from invalid element

By comparing the list of expected elements to the element used in the request you can determine that a typographical error occurred in the ltFlushAAACachegt element in the request

Error in the namespaces in the request fileThe internal error is also listed in the log if problems exist with namespaces in the request file The example in Figure 4-4 on page 38 shows a request where the namespace of the do-action was not specified By adding lsquodprsquo to the do-action this issue can be solved

Chapter 4 Debugging 37

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 48: DataPower: The XML Management Interface

Figure 4-4 Error from the namespace

44 Additional help

For additional help with debugging and creating requests you can always use the schemas and stylesheets that come with the device All functions attributes and elements are specified in those files You can find them in the store directory of the DataPower device

For AMP refer to

storeapp-mgmt-protocolwsdl

storeapp-mgmt-protocolxsd

For SOMA refer to

storexml-mgmt-basexsd

storexml-mgmt-opsxsd

storexml-mgmtwsdl

storexml-mgmtxsd

See also ldquoRelated publicationsrdquo on page 39 for additional resources

We hope this document helps you as you are creating and debugging your SOMA and AMP requests to administer your DataPower device

38 DataPower The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 49: DataPower: The XML Management Interface

Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this paper

IBM Redbooks

For information about ordering these publications see ldquoHow to get Redbooksrdquo on page 40 Note that some of the documents referenced here might be available in softcopy only

IBM WebSphere DataPower SOA Appliances Part I Overview and Getting Started REDP-4327

IBM WebSphere DataPower SOA Appliances Part II Authentication and Authorization REDP-4364

IBM WebSphere DataPower SOA Appliances Part III XML Security Guide REDP-4365

IBM WebSphere DataPower SOA Appliances Part IV Management and Governance REDP-4366

Online resources

These publications are also relevant as further information sources

WebSphere DataPower Integration Appliance firmware documentation download Web site

httpwwwibmcomsupportdocviewwssrs=2362ampuid=swg24014405

The following guides are available on the Web site

ndash DataPower XI 371 WebGUI Guide

ndash DataPower XI 371 Reference Guide

You will have to register for an IBM support or developerWorks user ID and password and also sign up to receive DataPower product information Both registrations are free

WebSphere DataPower SOA Appliances product support Web site

httpwwwibmcomsoftwareintegrationdatapowersupport

Managing services dynamically using WebSphere DataPower SOA Appliances with WebSphere Service Registry and Repository

httpwwwibmcomdeveloperworkswebspherelibrarytecharticles0802_rohmann0802_rohmannhtml

Locating the code samples on the Web

Code samples associated with this paper are available in softcopy on the Internet from either

The IBM Redbooks Web server Point your Web browser at

ftpwwwredbooksibmcomredbooksSG244446

copy Copyright IBM Corp 2008 All rights reserved 39

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 50: DataPower: The XML Management Interface

The IBM Redbooks Web site for this paper at

httpwwwredbooksibmcomredpiecesabstractsredp4446html

Select Additional Material to open the directory that corresponds to the Redpaper Download XMLsampszip file

How to get Redbooks

You can search for view or download Redbooks Redpapers Technotes draft publications and Additional materials as well as order hardcopy Redbooks at this Web site

ibmcomredbooks

Help from IBM

IBM Support and downloads

ibmcomsupport

IBM Global Services

ibmcomservices

40 DataPower The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice

Page 51: DataPower: The XML Management Interface

reg

REDP-4446-00

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization Experts from IBM Customers and Partners from around the world create timely technical information based on realistic scenarios Specific recommendations are provided to help you implement IT solutions more effectively in your environment

For more informationibmcomredbooks

Redpapertrade

WebSphere DataPower SOA Appliance The XML Management Interface

Appliance Management Protocol (AMP) configuration examples

SOAP Configuration Management (SOMA) examples

Debugging tips and common errors

The XML Management Interface is the third way to configure and administer the WebSphere DataPower SOA Appliance The other two are the WebGUI and the CLI

The DataPower device can be completely configured and managed through the XML Management Interface If enabled this interface allows administrators to send status and configuration requests to the DataPower appliance through a standard SOAP interface using SOAP messages The Appliance Management Protocol (AMP) is a series of commands developed after SOAP AMP is simple to use and is independent of any firmware version thereby providing a generalized way of managing the appliance

This interface requires the HTTPS protocol for all communication By default the interface acts as a Secure Sockets Layer (SSL) server using the default system keys that come with the device These keys are the same keys that are used for the WebGUI and Secure Shell (SSH) interface (such as a Command Line Interface (CLI)) If desired administrators can employ their own keys

Back cover

  • Go to the current abstract on ibmcomredbooks
  • Front cover
  • Contents
  • Notices
    • Trademarks
      • Preface
        • The team that wrote this paper
        • Become a published author
        • Comments welcome
          • Chapter 1 The Basics
            • 11 Overview of the XML Management Interface
              • 111 Appliance Management Protocol (AMP)
              • 112 SOAP Configuration Management (SOMA)
              • 113 WebService-Management (WSM)
              • 114 Web Services Distributed Management (WSDM)
              • 115 Service Level Monitoring (SLM)
              • 116 Universal Description Discovery and Integration (UDDI)
                • 12 XML Management Interface endpoints
                • 13 Setting up using the WebGUI
                • 14 Setting up by using the Command Line Interface
                • 15 How to send requests to the XML Management Interface
                  • Chapter 2 Appliance Management Protocol (AMP)
                    • 21 What is AMP
                    • 22 Configuration examples
                      • 221 Get the domain list of the device
                      • 222 Get device information
                      • 223 Enable (start) an application domain
                      • 224 Disable an application domain
                      • 225 Restart an application domain
                      • 226 Delete an application domain
                      • 227 Reboot the device
                      • 228 Reload the firmware
                      • 229 Upgrade the firmware
                          • Chapter 3 SOAP Configuration Management (SOMA)
                            • 31 What is SOMA
                            • 32 Configuration examples
                              • 321 Flush the document cache
                              • 322 Flush the stylesheet cache
                              • 323 Flush AAA cache
                              • 324 Flush RBM cache
                              • 325 Flush ARP cache
                              • 326 Set the log level in the default or the application domain
                              • 327 Create a backup of the device and the application domains
                              • 328 Restore backup
                              • 329 Copy a file to the device
                              • 3210 Delete a file from the device
                              • 3211 Create a directory on the device
                              • 3212 Remove a directory from the device
                              • 3213 Export an object
                              • 3214 Import an object
                              • 3215 Get status by monitoring the device
                                  • Sponsorships - Contact a qualified business partner
                                    • iSOA Group
                                      • Chapter 4 Debugging
                                        • 41 Enabling internal logging by using the WebGUI
                                        • 42 Debugging an invalid request
                                        • 43 Common errors
                                          • 431 Malformed content
                                          • 432 curl (52) Empty reply from server
                                          • 433 Authentication failure
                                          • 434 Access denied (from client)
                                          • 435 curl (7) couldnt connect to host
                                          • 436 Internal error
                                            • 44 Additional help
                                              • Related publications
                                                • IBM Redbooks
                                                • Online resources
                                                • Locating the code samples on the Web
                                                • How to get Redbooks
                                                • Help from IBM
                                                  • Back cover
                                                    • ltlt ASCII85EncodePages false AllowTransparency false AutoPositionEPSFiles true AutoRotatePages All Binding Left CalGrayProfile (Dot Gain 20) CalRGBProfile (sRGB IEC61966-21) CalCMYKProfile (US Web Coated 050SWOP051 v2) sRGBProfile (sRGB IEC61966-21) CannotEmbedFontPolicy Warning CompatibilityLevel 14 CompressObjects Tags CompressPages true ConvertImagesToIndexed true PassThroughJPEGImages true CreateJDFFile false CreateJobTicket false DefaultRenderingIntent Default DetectBlends true DetectCurves 00000 ColorConversionStrategy LeaveColorUnchanged DoThumbnails false EmbedAllFonts true EmbedOpenType false ParseICCProfilesInComments true EmbedJobOptions true DSCReportingLevel 0 EmitDSCWarnings false EndPage -1 ImageMemory 1048576 LockDistillerParams false MaxSubsetPct 100 Optimize true OPM 1 ParseDSCComments true ParseDSCCommentsForDocInfo true PreserveCopyPage true PreserveDICMYKValues true PreserveEPSInfo true PreserveFlatness true PreserveHalftoneInfo false PreserveOPIComments false PreserveOverprintSettings true StartPage 1 SubsetFonts true TransferFunctionInfo Apply UCRandBGInfo Preserve UsePrologue false ColorSettingsFile () AlwaysEmbed [ true ] NeverEmbed [ true ] AntiAliasColorImages false CropColorImages true ColorImageMinResolution 300 ColorImageMinResolutionPolicy OK DownsampleColorImages true ColorImageDownsampleType Bicubic ColorImageResolution 300 ColorImageDepth -1 ColorImageMinDownsampleDepth 1 ColorImageDownsampleThreshold 150000 EncodeColorImages true ColorImageFilter DCTEncode AutoFilterColorImages true ColorImageAutoFilterStrategy JPEG ColorACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt ColorImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000ColorACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000ColorImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasGrayImages false CropGrayImages true GrayImageMinResolution 300 GrayImageMinResolutionPolicy OK DownsampleGrayImages true GrayImageDownsampleType Bicubic GrayImageResolution 300 GrayImageDepth -1 GrayImageMinDownsampleDepth 2 GrayImageDownsampleThreshold 150000 EncodeGrayImages true GrayImageFilter DCTEncode AutoFilterGrayImages true GrayImageAutoFilterStrategy JPEG GrayACSImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt GrayImageDict ltlt QFactor 015 HSamples [1 1 1 1] VSamples [1 1 1 1] gtgt JPEG2000GrayACSImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt JPEG2000GrayImageDict ltlt TileWidth 256 TileHeight 256 Quality 30 gtgt AntiAliasMonoImages false CropMonoImages true MonoImageMinResolution 1200 MonoImageMinResolutionPolicy OK DownsampleMonoImages true MonoImageDownsampleType Bicubic MonoImageResolution 1200 MonoImageDepth -1 MonoImageDownsampleThreshold 150000 EncodeMonoImages true MonoImageFilter CCITTFaxEncode MonoImageDict ltlt K -1 gtgt AllowPSXObjects false CheckCompliance [ None ] PDFX1aCheck false PDFX3Check false PDFXCompliantPDFOnly false PDFXNoTrimBoxError true PDFXTrimBoxToMediaBoxOffset [ 000000 000000 000000 000000 ] PDFXSetBleedBoxToMediaBox true PDFXBleedBoxToTrimBoxOffset [ 000000 000000 000000 000000 ] PDFXOutputIntentProfile () PDFXOutputConditionIdentifier () PDFXOutputCondition () PDFXRegistryName () PDFXTrapped False Description ltlt CHS ltFEFF4f7f75288fd94e9b8bbe5b9a521b5efa7684002000500044004600206587686353ef901a8fc7684c976262535370673a548c002000700072006f006f00660065007200208fdb884c9ad88d2891cf62535370300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c676562535f00521b5efa768400200050004400460020658768633002gt CHT ltFEFF4f7f752890194e9b8a2d7f6e5efa7acb7684002000410064006f006200650020005000440046002065874ef653ef5728684c9762537088686a5f548c002000700072006f006f00660065007200204e0a73725f979ad854c18cea7684521753706548679c300260a853ef4ee54f7f75280020004100630072006f0062006100740020548c002000410064006f00620065002000520065006100640065007200200035002e003000204ee553ca66f49ad87248672c4f86958b555f5df25efa7acb76840020005000440046002065874ef63002gt DAN ltFEFF004200720075006700200069006e0064007300740069006c006c0069006e006700650072006e0065002000740069006c0020006100740020006f007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e007400650072002000740069006c0020006b00760061006c00690074006500740073007500640073006b007200690076006e0069006e006700200065006c006c006500720020006b006f007200720065006b007400750072006c00e60073006e0069006e0067002e0020004400650020006f007000720065007400740065006400650020005000440046002d0064006f006b0075006d0065006e0074006500720020006b0061006e002000e50062006e00650073002000690020004100630072006f00620061007400200065006c006c006500720020004100630072006f006200610074002000520065006100640065007200200035002e00300020006f00670020006e0079006500720065002egt DEU ltFEFF00560065007200770065006e00640065006e0020005300690065002000640069006500730065002000450069006e007300740065006c006c0075006e00670065006e0020007a0075006d002000450072007300740065006c006c0065006e00200076006f006e002000410064006f006200650020005000440046002d0044006f006b0075006d0065006e00740065006e002c00200076006f006e002000640065006e0065006e002000530069006500200068006f00630068007700650072007400690067006500200044007200750063006b006500200061007500660020004400650073006b0074006f0070002d0044007200750063006b00650072006e00200075006e0064002000500072006f006f0066002d00470065007200e400740065006e002000650072007a0065007500670065006e0020006d00f60063006800740065006e002e002000450072007300740065006c006c007400650020005000440046002d0044006f006b0075006d0065006e007400650020006b00f6006e006e0065006e0020006d006900740020004100630072006f00620061007400200075006e0064002000410064006f00620065002000520065006100640065007200200035002e00300020006f0064006500720020006800f600680065007200200067006500f600660066006e00650074002000770065007200640065006e002egt ESP ltFEFF005500740069006c0069006300650020006500730074006100200063006f006e0066006900670075007200610063006900f3006e0020007000610072006100200063007200650061007200200064006f00630075006d0065006e0074006f0073002000640065002000410064006f0062006500200050004400460020007000610072006100200063006f006e00730065006700750069007200200069006d0070007200650073006900f3006e002000640065002000630061006c006900640061006400200065006e00200069006d0070007200650073006f0072006100730020006400650020006500730063007200690074006f00720069006f00200079002000680065007200720061006d00690065006e00740061007300200064006500200063006f00720072006500630063006900f3006e002e002000530065002000700075006500640065006e00200061006200720069007200200064006f00630075006d0065006e0074006f00730020005000440046002000630072006500610064006f007300200063006f006e0020004100630072006f006200610074002c002000410064006f00620065002000520065006100640065007200200035002e003000200079002000760065007200730069006f006e0065007300200070006f00730074006500720069006f007200650073002egt FRA ltFEFF005500740069006c006900730065007a00200063006500730020006f007000740069006f006e00730020006100660069006e00200064006500200063007200e900650072002000640065007300200064006f00630075006d0065006e00740073002000410064006f00620065002000500044004600200070006f007500720020006400650073002000e90070007200650075007600650073002000650074002000640065007300200069006d007000720065007300730069006f006e00730020006400650020006800610075007400650020007100750061006c0069007400e90020007300750072002000640065007300200069006d007000720069006d0061006e0074006500730020006400650020006200750072006500610075002e0020004c0065007300200064006f00630075006d0065006e00740073002000500044004600200063007200e900e90073002000700065007500760065006e0074002000ea0074007200650020006f007500760065007200740073002000640061006e00730020004100630072006f006200610074002c002000610069006e00730069002000710075002700410064006f00620065002000520065006100640065007200200035002e0030002000650074002000760065007200730069006f006e007300200075006c007400e90072006900650075007200650073002egt ITA ltFEFF005500740069006c0069007a007a006100720065002000710075006500730074006500200069006d0070006f007300740061007a0069006f006e00690020007000650072002000630072006500610072006500200064006f00630075006d0065006e00740069002000410064006f006200650020005000440046002000700065007200200075006e00610020007300740061006d007000610020006400690020007100750061006c0069007400e00020007300750020007300740061006d00700061006e0074006900200065002000700072006f006f0066006500720020006400650073006b0074006f0070002e0020004900200064006f00630075006d0065006e007400690020005000440046002000630072006500610074006900200070006f00730073006f006e006f0020006500730073006500720065002000610070006500720074006900200063006f006e0020004100630072006f00620061007400200065002000410064006f00620065002000520065006100640065007200200035002e003000200065002000760065007200730069006f006e006900200073007500630063006500730073006900760065002egt JPN ltFEFF9ad854c18cea51fa529b7528002000410064006f0062006500200050004400460020658766f8306e4f5c6210306b4f7f75283057307e30593002537052376642306e753b8cea3092670059279650306b4fdd306430533068304c3067304d307e3059300230c730b930af30c830c330d730d730ea30f330bf3067306e53705237307e305f306f30d730eb30fc30d57528306b9069305730663044307e305930023053306e8a2d5b9a30674f5c62103055308c305f0020005000440046002030d530a130a430eb306f3001004100630072006f0062006100740020304a30883073002000410064006f00620065002000520065006100640065007200200035002e003000204ee5964d3067958b304f30533068304c3067304d307e30593002gt KOR ltFEFFc7740020c124c815c7440020c0acc6a9d558c5ec0020b370c2a4d06cd0d10020d504b9b0d1300020bc0f0020ad50c815ae30c5d0c11c0020ace0d488c9c8b85c0020c778c1c4d560002000410064006f0062006500200050004400460020bb38c11cb97c0020c791c131d569b2c8b2e4002e0020c774b807ac8c0020c791c131b41c00200050004400460020bb38c11cb2940020004100630072006f0062006100740020bc0f002000410064006f00620065002000520065006100640065007200200035002e00300020c774c0c1c5d0c11c0020c5f40020c2180020c788c2b5b2c8b2e4002egt NLD (Gebruik deze instellingen om Adobe PDF-documenten te maken voor kwaliteitsafdrukken op desktopprinters en proofers De gemaakte PDF-documenten kunnen worden geopend met Acrobat en Adobe Reader 50 en hoger) NOR ltFEFF004200720075006b00200064006900730073006500200069006e006e007300740069006c006c0069006e00670065006e0065002000740069006c002000e50020006f0070007000720065007400740065002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740065007200200066006f00720020007500740073006b00720069006600740020006100760020006800f800790020006b00760061006c00690074006500740020007000e500200062006f007200640073006b0072006900760065007200200065006c006c00650072002000700072006f006f006600650072002e0020005000440046002d0064006f006b0075006d0065006e00740065006e00650020006b0061006e002000e50070006e00650073002000690020004100630072006f00620061007400200065006c006c00650072002000410064006f00620065002000520065006100640065007200200035002e003000200065006c006c00650072002000730065006e006500720065002egt PTB ltFEFF005500740069006c0069007a006500200065007300730061007300200063006f006e00660069006700750072006100e700f50065007300200064006500200066006f0072006d00610020006100200063007200690061007200200064006f00630075006d0065006e0074006f0073002000410064006f0062006500200050004400460020007000610072006100200069006d0070007200650073007300f5006500730020006400650020007100750061006c0069006400610064006500200065006d00200069006d00700072006500730073006f0072006100730020006400650073006b0074006f00700020006500200064006900730070006f00730069007400690076006f0073002000640065002000700072006f00760061002e0020004f007300200064006f00630075006d0065006e0074006f00730020005000440046002000630072006900610064006f007300200070006f00640065006d0020007300650072002000610062006500720074006f007300200063006f006d0020006f0020004100630072006f006200610074002000650020006f002000410064006f00620065002000520065006100640065007200200035002e0030002000650020007600650072007300f50065007300200070006f00730074006500720069006f007200650073002egt SUO ltFEFF004b00e40079007400e40020006e00e40069007400e4002000610073006500740075006b007300690061002c0020006b0075006e0020006c0075006f0074002000410064006f0062006500200050004400460020002d0064006f006b0075006d0065006e007400740065006a00610020006c0061006100640075006b006100730074006100200074007900f6007000f60079007400e400740075006c006f0073007400750073007400610020006a00610020007600650064006f007300740075007300740061002000760061007200740065006e002e00200020004c0075006f0064007500740020005000440046002d0064006f006b0075006d0065006e00740069007400200076006f0069006400610061006e0020006100760061007400610020004100630072006f0062006100740069006c006c00610020006a0061002000410064006f00620065002000520065006100640065007200200035002e0030003a006c006c00610020006a006100200075007500640065006d006d0069006c006c0061002egt SVE ltFEFF0041006e007600e4006e00640020006400650020006800e4007200200069006e0073007400e4006c006c006e0069006e006700610072006e00610020006f006d002000640075002000760069006c006c00200073006b006100700061002000410064006f006200650020005000440046002d0064006f006b0075006d0065006e00740020006600f600720020006b00760061006c00690074006500740073007500740073006b0072006900660074006500720020007000e5002000760061006e006c00690067006100200073006b0072006900760061007200650020006f006300680020006600f600720020006b006f007200720065006b007400750072002e002000200053006b006100700061006400650020005000440046002d0064006f006b0075006d0065006e00740020006b0061006e002000f600700070006e00610073002000690020004100630072006f0062006100740020006f00630068002000410064006f00620065002000520065006100640065007200200035002e00300020006f00630068002000730065006e006100720065002egt ENU (Use these settings to create Adobe PDF documents for quality printing on desktop printers and proofers Created PDF documents can be opened with Acrobat and Adobe Reader 50 and later) gtgt Namespace [ (Adobe) (Common) (10) ] OtherNamespaces [ ltlt AsReaderSpreads false CropImagesToFrames true ErrorControl WarnAndContinue FlattenerIgnoreSpreadOverrides false IncludeGuidesGrids false IncludeNonPrinting false IncludeSlug false Namespace [ (Adobe) (InDesign) (40) ] OmitPlacedBitmaps false OmitPlacedEPS false OmitPlacedPDF false SimulateOverprint Legacy gtgt ltlt AddBleedMarks false AddColorBars false AddCropMarks false AddPageInfo false AddRegMarks false ConvertColors NoConversion DestinationProfileName () DestinationProfileSelector NA Downsample16BitImages true FlattenerPreset ltlt PresetSelector MediumResolution gtgt FormElements false GenerateStructure true IncludeBookmarks false IncludeHyperlinks false IncludeInteractive false IncludeLayers false IncludeProfiles true MultimediaHandling UseObjectSettings Namespace [ (Adobe) (CreativeSuite) (20) ] PDFXOutputIntentProfileSelector NA PreserveEditing true UntaggedCMYKHandling LeaveUntagged UntaggedRGBHandling LeaveUntagged UseDocumentBleed false gtgt ]gtgt setdistillerparamsltlt HWResolution [2400 2400] PageSize [612000 792000]gtgt setpagedevice