Brocade, the B-wing symbol, Brocade Assurance, ADX, AnyIO, DCX, Fabric OS, FastIron, HyperEdge, ICX, MLX, MyBrocade, NetIron,
OpenScript, VCS, VDX, and Vyatta are registered trademarks, and The Effortless Network and the On-Demand Data Center are
trademarks of Brocade Communications Systems, Inc., in the United States and in other countries. Other brands and product
names mentioned may be trademarks of others.
Notice: This document is for informational purposes only and does not set forth any warranty, expressed or implied, concerning
any equipment, equipment feature, or service offered or to be offered by Brocade. Brocade reserves the right to make changes to
this document at any time, without notice, and assumes no responsibility for its use. This informational document describes
features that may not be currently available. Contact a Brocade sales office for information on feature and product availability.
Export of technical data contained in this document may require an export license from the United States government.
The authors and Brocade Communications Systems, Inc. assume no liability or responsibility to any person or entity with respect
to the accuracy of this document or any loss, cost, liability, or damages arising from the information contained herein or the
computer programs that accompany it.
The product described by this document may contain open source software covered by the GNU General Public License or other
open source license agreements. To find out which open source software is included in Brocade products, view the licensing
terms applicable to the open source software, and obtain a copy of the programming source code, please visit http://
www.brocade.com/support/oscd.
Brocade Communications Systems, Incorporated
Corporate and Latin American Headquarters
Brocade Communications Systems, Inc.
130 Holger Way
San Jose, CA 95134
Tel: 1-408-333-8000
Fax: 1-408-333-8101
E-mail: info@brocade.com
European Headquarters
Brocade Communications Switzerland Sàrl
Centre Swissair
Tour B - 4ème étage
29, Route de l'Aéroport
Case Postale 105
CH-1215 Genève 15
Switzerland
Tel: +41 22 799 5640
Fax: +41 22 799 5641
E-mail: emea-info@brocade.com
Asia-Pacific Headquarters
Brocade Communications Systems China HK, Ltd.
No. 1 Guanghua Road
Chao Yang District
Units 2718 and 2818
Beijing 100020, China
Tel: +8610 6588 8888
Fax: +8610 6588 9999
E-mail: china-info@brocade.com
Asia-Pacific Headquarters
Brocade Communications Systems Co., Ltd. (Shenzhen WFOE)
Citic Plaza
No. 233 Tian He Road North
Unit 1308 – 13th Floor
Guangzhou, China
Tel: +8620 3891 2000
Fax: +8620 3891 2111
E-mail: china-info@brocade.com
Brocade Virtual ADX XML API Programmer’s Guidev
53-1003248-01
viBrocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Preface
Document conventions
This section describes text formatting conventions and important notice formats that may be used
in this document.
Text formatting
The following text formatting conventions may be used in the flow of the text to highlight specific
words or phrases.
FormatDescription
bold textIdentifies command names
Identifies keywords
Identifies the names of user-manipulated GUI elements
Identifies text to enter at the GUI or CLI
italic textProvides emphasis
Identifies variables and modifiers
Identifies paths and Internet addresses
Identifies document titles
code
Identifies CLI output
Identifies command syntax examples
Brocade Virtual ADX XML API Programmer’s Guidevii
53-1003248-01
Command syntax conventions
NOTE
ATTENTION
CAUTION
DANGER
ConventionDescription
bold textIdentifies command names, keywords, and command options.
italic textIdentifies variables.
[ ]
{ x | y |z }
Syntax components displayed within square brackets are optional.
A choice of required parameters is enclosed in curly braces separated
byvertical bars. You must select one.
x | y
< >
A vertical bar separates mutually exclusive elements.
Nonprinting characters, for example, passwords, are enclosed in angle
brackets.
...
\
Repeat the previous element. For example, member [member...].
Indicates a “soft” line break in command examples. If a backslash
separates two lines of a command input, enter the entire command at the
prompt without the backslash.
Notes, cautions, and warnings
The following notices and statements may be used in this document. They are listed below in order
of increasing severity of potential hazards.
A note provides a tip, guidance or advice, emphasizes important information, or provides a reference
to related information.
An Attention statement indicates a stronger note, for example, to alert you when traffic might be
interrupted or the device might reboot.
A Caution statement alerts you to situations that can be potentially hazardous to you or cause
damage to hardware, firmware, software, or data.
A Danger statement indicates conditions or situations that can be potentially lethal or extremely
hazardous to you. Safety labels are also attached directly to products to warn of these conditions
or situations.
viiiBrocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Brocade resources
To get up-to-the-minute information, go to http://my.brocade.com to register at no cost for a user ID
and password.
Release notes are available at http://my.brocade.com.
White papers, online demonstrations, and data sheets are available through the Brocade website
at:
Select Application Delivery Switches on this page to navigate to the relevant product information.
Contacting Brocade Technical Support
As a Brocade customer, you can contact Brocade Technical Support 24x7 online, by telephone, or
by e-mail. Brocade OEM customers contact their OEM/Solutions provider.
For product support information and the latest information on contacting the Technical Assistance
Center, go to http://www.brocade.com/services-support/index.html
If you have purchased Brocade product support directly from Brocade, use one of the following
methods to contact the Brocade Technical Assistance Center 24x7.
OnlineTelephoneEmail
Preferred method of contact
for non-urgent issues:
• My Cases through
MyBrocade
• Software downloads &
licensing tools
• Knowledge Base
Required for Sev 1-Critical and
Sev 2-High issues:
• Continental US:
1-800-752-8061
• Europe, Middle East, Africa,
and Asia Pacific: +800-AT
FIBREE (+800 28 34 27
33)
support@brocade.com
Please include:
• Problem summary
• Serial number
• Installation details
• Environment description
• For areas unable to access
toll free number:
+1-408-333-6061
• Toll-free numbers are
available in many countries.
If you have purchased Brocade product support from a Brocade OEM/Solution Provider, contact
your OEM/Solution Provider for all of your product support needs.
• OEM/Solution Providers are trained and certified by Brocade to support Brocade® products.
• Brocade provides backline support for issues that cannot be resolved by the OEM/Solution
Provider.
• Brocade Supplemental Support augments your existing OEM support contract, providing direct
access to Brocade expertise. For more information, contact Brocade or your OEM.
Brocade Virtual ADX XML API Programmer’s Guideix
53-1003248-01
Document feedback
• For questions regarding service levels and response times, contact your OEM/Solution
Provider.
Document feedback
Quality is our first concern at Brocade and we have made every effort to ensure the accuracy and
completeness of this document. However, if you find an error or an omission, or you think that a
topic needs further development, we want to hear from you. You can provide feedback in two ways:
• Through the online feedback form in the HTML documents posted on
http://www.brocade.com.
• By sending your feedback to documentation@brocade.com
Provide the publication title, part number, and as much detail as possible, including the topic
heading and page number if applicable, as well as your suggestions for improvement.
•Enabling a web service on a Brocade Virtual ADX . . . . . . . . . . . . . . . . . . . . . 6
Programmatic interface to Brocade Virtual ADX : XML APIs
XML APIs are a programmatic interface to access Brocade Virtual ADX. It uses the SOAP protocol
over HTTP and allows customers an automated management of their Brocade Virtual ADX devices.
1
The fundamental entity in the XML API programming is the WSDL – an XML based text file which
specifies the methods exposed by the device, and the ways to access it. Client applications have to
be written to access the device using XML API based on the specifications in the WSDL.
Brocade Virtual ADX XML API Programmer’s Guide1
53-1003248-01
Purpose of the WSDL
1
The following diagram is a pictorial description of the XML API framework.
FIGURE 1XML API Framework
Purpose of the WSDL
Simple Object Access Protocol
Web Service Definition Language (Application Programming Interface)
XML SOAP interface overview
An XML SOAP interface for Brocade Virtual ADX application delivery controllers gives application
administrators a programmatic way to access and manage ADX platforms through published APIs.
It allows customers to achieve better orchestration and control over their application delivery
infrastructure. Application administrators can create custom scripts using the XML SOAP interface
to conduct several configuration tasks, gather system statistics, and simplify day-to-day operational
tasks.
2Brocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Users have access to documented input and output characteristics for each XML SOAP method, the
NOTE
data types, and their values in a platform-independent way. The platform independence is achieved
through use of XML (SOAP over HTTP) as the medium for information exchange. One major
advantage of the XML-API is significant improvement in latency for accessing information from your
ADX devices. The reason for this advantage is that HTTP is optimized for bulk data transfer, unlike
SSH or Telnet, which are traditionally used for data access. Latency is measured as the time
difference between a request sent to the ADX and a meaningful response becoming available at
the client for further action. Such low latency environments are extremely useful in large
application delivery deployments, where latency is expected to be as low as possible.
WSDL location
You can obtain the four WSDL files by accessing a Brocade Virtual ADX through the HTTP interface
using the following URLs:
The <device-ip> variable in the URL refers to the IP address of the management port on the
Brocade Virtual ADX.
Accessing the client API using SOAP
The client application must send an HTTP authentication header before invoking every SOAP
request. The username and password in the authentication header must have super user privileges
on the Brocade Virtual ADX. The HTTP authentication header must also contain context information
along with the username and password.
Creating client-specific APIs from client stubs
Use cases
The following examples provide a framework for developing ADX-specific programs.
Adding and binding a real server and a VIP
1. Add a real server.
2. Add a real server port.
3. Add a virtual server and virtual server port.
Brocade Virtual ADX XML API Programmer’s Guide3
53-1003248-01
Creating client-specific APIs from client stubs
1
4. Bind the real server to the virtual server.
5. Save the configuration.
Each request is authenticated independently.
Refer to “Example: Adding and binding a real server and a VIP” for examples in Perl, Java, and C#.
Unbinding a real server from a VIP
1. Unbind a previously added real server from the virtual server.
2. Remove the real server and the virtual server.
3. Save the configuration.
Refer to “Example: Unbinding a real server from a VIP” for examples in Perl, Java, and C#.
Provisioning real and virtual servers
1. Add a list of real servers with common parameters.
2. Add a virtual server and real server ports to the VIP.
3. Remove or disable a list of real servers that has a given string in its name, using regular
expressions or wild cards if needed.
4. Remove a real server and reuse its IP address for another real server.
Refer to “Example - Provisioning real and virtual servers” for examples in C#.
Monitoring the system
1. List all failed real server ports and real servers.
2. List all failed VIP ports and VIPs.
3. List all unplugged real servers (where the MAC address is unknown in the show server real
output).
4. Monitor the status of a given real server port.
5. Monitor the status of a VIP port.
6. Monitor the current connections of a real server.
7. Monitor the current connections of a VIP.
8. Monitor the total current connections of the system.
9. Monitor the CPU and the memory of the system.
Code for simple SOAP clients
The following code examples illustrate how to work with the SOAP protocol.
Perl example
This example shows the output from the script "getChassisInfo.pl" and then shows the contents of
the script.
4Brocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Creating client-specific APIs from client stubs
The following output results from the execution of the "getChassisInfo.pl" script:
C:\>getChassisInfo.pl
Chassis Model : SI-1216-4-PREM
Chassis Serial : E2SA02F038
The contents of the “getChassisInfo.pl” script are as follows:
Before a Brocade Virtual ADX can acknowledge any SOAP requests, it must have the
web-management command configured with at least the soap-service option:
web-managment
Syntax: web-managment [option[ ...]]
Options:
allow-no-password Allow web server to have no password
connection-receive-timeout Web connection receive timeout
enable Enable web management
frame Allow to disable or enable a frame
front-panel Enable front panel
hp-top-tools Enable the support of HP TOP Tools
http Enable the support of http server
list-menu Show web menu as a list
page-menu Enable page menu
page-size Maximum number of entries in a page
refresh Page refresh (polling time) in seconds
session-timeout Web session timeout in minutes (value 0 means no
timeout)
soap-service Enable SOAP Services
You can use the XML API in this guide to perform operations on the various features and functions
that are supported on the ADX platform.
Most APIs begin with one of the listed keywords in column 1 of the table below. The keyword
indicates the type of operation that can be performed using the API. The arguments to these APIs
form the various inputs for the operations. For greater flexibility, each API expects a minimum
number of mandatory attributes.
2
The following table contains the basic operations, their descriptions, and examples.
TABLE 1API operations
Basic API
operations
createThese APIs are used to create objects such as a real server or a virtual
deleteThese APIs are used to delete objects such as a real server on the
enableThese APIs are used to enable objects after they are created on the
disableThese APIs are used to disable objects after they are created and
updateThese APIs are used to update the configuration of an existing object.
clearThese APIs are used to clear an attribute value of an object and set it
setThese APIs are used to set one or more specific attributes of an object
getThese APIs are used to obtain the configuration and statistics of an
DescriptionExample
createVlan
server on the Brocade Virtual ADX platform. All of the create APIs
require a few mandatory attributes.
deleteIPSubnetVlans
Brocade Virtual ADX platform.
enableGlobalFlowCo
Brocade Virtual ADX platform. The objects that need to be enabled are
the inputs to these APIs.
enabled on the Brocade Virtual ADX platform. The objects can be
disabled without adjusting their current configuration.
If the value of an attribute is not set, it is removed from the
configuration of the object.
back to the default value.
to a user-defined value.
object.
ntrol
disableInterfaces
updateIPSubnetVlan
s
clearIPRoute
setInterfaceConfig.
getConfiguration
Brocade Virtual ADX XML API Programmer’s Guide7
53-1003248-01
API naming conventions
2
TABLE 1API operations
Basic API
operations
DescriptionExample
getAllThese APIs are used to obtain the configuration and statistics of more
than one object. The Brocade Virtual ADX device has a maximum
number of objects that can be returned on the buffer. The resultant
number of objects could be less then the total number of objects
available on the Brocade Virtual ADX device. To facilitate the collection
of details of all of the objects, these APIs contain "startIndex" and
"numRetrieved" inputs.
The “startIndex” is an index value with which you can retrieve the
information.
The "numRetrieved" is the number of entries that you want to retrieve.
The response is limited to the number of objects that can be retrieved.
bindThese APIs are used to bind one object to another object in the
Brocade Virtual ADX device, for example, binding a real server to a
virtual server configured on the Brocade Virtual ADX platform.
unbindThese APIs are similar to the bind APIs, and they are used to unbind an
object from another object on the Brocade Virtual ADX platform.
API naming conventions
All of the APIs and enumerations follow the CamelCase naming convention. The API name is formed
by multiple words that are joined together as a single word. The APIs begin with a lowercase letter.
The first letter of subsequent words is capitalized so that each word that makes up the name can
be read easily. Two letter abbreviations are also capitalized if not the first word in the API name, for
example, addAcl.
getAllIPSubnetVlans
bindSipPolicyToFilter
unbindSipServers
The names of data structures begin with a capital letter, but all of the other API naming convention
rules apply, for example, RealServerMonitoringDetails and AclID.
Request and response XML
Most APIs make a query or a request and expect a response to the query. These requests and
responses have a data structure in which they are sent and received respectively. The data
structures contain the names of the data required and their respective data types.
Tab le 28 contains the parameters required for the method.
TABLE 28Parameters
NameTypePresenceRulesDescription
reloadConfigReloadConfiguration MandatoryIdentifies the configuration of the Brocade
Virtual ADX reload.
Return value
Tab le 29 contains the return value of the method.
TABLE 29Return value
NameTypeDescription
messagestringMessage
Error messages
List of Error Messages
writeConfig
Description
Saves the system configuration to the startup configuration file.
Error messages
List of Error Messages
18Brocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Methods
3
System - High Availability
Description
High Availability refers to a system or component that is continuously operational for a long time
without failing. The following APIs configure High Availability system functions on the Brocade
Virtual ADX.
addHABackupPort
Description
Adds a backup port in the hot standby mode.
Parameters
Tab le 30 contains the parameters required for the method.
TABLE 30Parameters
NameTypePresenceRulesDescription
backupPortHAbackupPortOptionalIdentifies the physical Ethernet port which is
used as the backup port. A system reload is
required after invoking this API.
Error messages
List of Error Messages
addHARouterPort
Description
Adds a router port in the hot standby mode.
Parameters
Tab le 31 contains the parameters required for the method.
TABLE 31Parameters
NameTypePresenceRulesDescription
routerPortHARouterPort[ ]OptionalIdentifies the physical Ethernet port which is
used as the router port. A system reload is
required after invoking this API.
Error messages
List of Error Messages
clearBackupNodeConfiguration
Description
Clears the configuration of the backup node.
Brocade Virtual ADX XML API Programmer’s Guide19
53-1003248-01
3
Methods
Parameters
Tab le 32 contains the parameters required for the method.
TABLE 32Parameters
NameTypePresenceRulesDescription
attributehaNodeAttributeEnum[ ] OptionalIdentifies the configuration information for the
backup server.
Error messages
List of Error Messages
createVipGroup
Description
Creates the VIP group and add it to VRID configuration.
Parameters
Tab le 33 contains the parameters required for the method.
TABLE 33Parameters
NameTypePresenceRulesDescription
configHAVipGroupConfiguration MandatoryIdentifies the configuration required for the
VIP group.
Error messages
List of Error Messages
deleteHABackupPort
Description
Deletes the backup port and removes the hot standby HA configuration.
Parameters
Tab le 34 contains the parameters required for the method.
TABLE 34Parameters
NameTypePresenceRulesDescription
backupPortHAbackupPortOptionalIdentifies the physical Ethernet port which will be
used as backup port.
Error messages
List of Error Messages
deleteHARouterPort
Description
Deletes a router port.
20Brocade Virtual ADX XML API Programmer’s Guide
53-1003248-01
Loading...
+ 848 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.