web service api reference guide for cisco application ... · iii api reference guide for cisco...

Web Service API Reference Guide for Cisco Application Networking Manager 4.3Version 4.3 June 2011

Americas HeadquartersCisco Systems, Inc.170 West Tasman DriveSan Jose, CA 95134-1706 USAhttp://www.cisco.comTel: 408 526-4000

800 553-NETS (6387)Fax: 408 527-0883

Text Part Number: OL-24855-01

http://www.cisco.com

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB’s public domain version of the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS” WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental.

API Reference Guide for Cisco Application Networking Manager 4.3 © 2011 Cisco Systems, Inc. All rights reserved.

http://www.cisco.com/go/trademarks

OL-24855-01

C O N T E N T S

Preface ix

Audience ix

Organization ix

Related Documentation x

Conventions x

Open-Source Software Included in the Cisco Application Networking Manager xi

Obtaining Documentation and Submitting a Service Request xi

C H A P T E R 1 Introduction to the Cisco ANM Web Services API 1-1

ANM Web Services API Overview 1-1

Enabling the Web Services Interface 1-2

Web Services Description Language 1-2

Using the ANM Web Services API 1-3

Required Software, Web Standards, and Supported Hardware 1-3

Generating the Client Code to Invoke a Web Service 1-3

C H A P T E R 2 ANM Web Services API 2-1

Mapping Table 2-2

C H A P T E R 3 Web Service Objects 3-1

C H A P T E R 4 Troubleshooting Problems 4-1

SOAP Message Traffic and Time Taken to Invoke an API 4-1

Custom Application Errors 4-1

Modifying the Number of Concurrent Sessions Allowed 4-3

Use Case 1: SampleWSClient A-1

Use Case 2: ActivateSuspendSfRserverClient A-5

Use Case 3: Virtual Server WS Client A-10

Use Case 4: GSSWSClient A-17

I N D E X

iiiAPI Reference Guide for Cisco Application Networking Manager 4.3

Contents

ivAPI Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

Preface

This guide describes the Cisco Application Networking Manager Web Services application program interface (API) implementation and explains how to use it to manage your network. This preface provides information about using this guide. This preface includes the following sections:

• Audience, page ix

• Organization, page ix

• Related Documentation, page x

• Conventions, page x

• Open-Source Software Included in the Cisco Application Networking Manager, page xi

• Obtaining Documentation and Submitting a Service Request, page xi

AudienceThis API guide is written for the knowledgeable application programmer who understands the basic architecture of the Cisco Application Networking Manager (ANM). This document provides detailed descriptions of Web Service APIs supported by ANM. Depending on the configuration required, readers should have specific knowledge in the following areas:

• Networking and data communications

• Network security

• Router configuration

• Datacenter products

Organization This document contains the following sections:

• Chapter 1, “Introduction to the Cisco ANM Web Services API” provides an overview of the programmable interface and the methods and schemas used to perform configuration operations using the API.

• Chapter 2, “ANM Web Services API” lists all APIs and describes them.

• Chapter 3, “Web Service Objects” lists the data types that are defined structures or objects in the ANM Web Services API.

ixAPI Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

Preface

• Chapter 4, “Troubleshooting Problems” lists the custom application errors.

• Appendix A, “Use Case Examples” lists the use case sample code examples.

Related DocumentationIn addition to this installation guide, the Application Networking Manager (ANM) documentation set includes the following publications. You can access the ANM documentation on www.cisco.com at: http://www.cisco.com/en/US/products/ps6904/tsd_products_support_series_home.html.

• Installation Guide for the Cisco Application Networking Manager—Includes complete installation and configuration information for the ANM software.

• Installation Guide for the Cisco Application Networking Manager Virtual Appliance—Includes complete information about ANM virtual appliance functionality, installation, configuration, and administration procedures.

• User Guide for the Cisco Application Networking Manager—Includes complete information about ANM functionality and detailed procedures for its use. Contains all of the information found in online help. Available either on cisco.com or from the ANM online help.

• Context-sensitive online help—Includes help topics for all pages in the UI (also provides access to PDFs of the user guide). Select an option from the ANM GUI, and click Help.

• Supported Devices Table for the Cisco Application Networking Manager—Includes complete supported device and firmware versions for ANM.

• Supplemental License Agreement for the Cisco Application Networking Manager—Describes licensing limitations and restrictions.

ConventionsThis document uses the following conventions:

Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication.

Item Convention

Commands and keywords boldface font

Variables for which you supply values italic font

Displayed session and system information screen font

Information you enter boldface screen font

Variables you enter italic screen font

Menu items and button names boldface font

Choosing a menu item in paragraphs Option > Network Preferences

Choosing a menu item in tables Option > Network Preferences

xAPI Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

Preface

Caution Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data.

Open-Source Software Included in the Cisco Application Networking Manager

• The Cisco Application Networking Manager includes the following open-source software, which is covered by the Apache 2.0 license (http://www.apache.org/): Ant, Avalon Logkit, Commons, Ehcache, Jetty, Log4J, Oro, Commons_Logging, Xmlrpc.

• The Cisco Application Networking Manager includes the following open-source software, which is covered by The Legion of the Bouncy Castle (http://www.bouncycastle.org/licence.html) license: BouncyCastle.

• The Cisco Application Networking Manager includes the following open-source software, which is covered by the GNU Lesser General Public License Version 2.1 (http://www.gnu.org/licenses/lgpl.html): c3p0-0.9.0.2.jar, Enterprise DT, Jasperreports 1.2, Jcommon 1.2, Jfreechart 1.0.1.

• The Cisco Application Networking Manager includes the following open-source software, which is covered by the Mozilla Public License Version 1.1 (http://www.mozilla.org/MPL/1.1/): Itext 1.4.

Obtaining Documentation and Submitting a Service RequestFor information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What’s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at:

http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

Subscribe to the What’s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0.

xiAPI Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

http://www.apache.org/



http://www.bouncycastle.org/licence.html



http://www.cisco.com/en/US/docs/general/whatsnew/whatsnew.html

http://www.gnu.org/licenses/lgpl.html

http://www.gnu.org/licenses/lgpl.html

http://www.mozilla.org/MPL/1.1/

http://www.mozilla.org/MPL/1.1/

Preface

xiiAPI Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

API Reference GOL-24855-01

C H A P T E R 1
Introduction to the Cisco ANM Web Services API
This chapter describes the Cisco ANM Web Services application programming interface (API), which provides a programmable interface for system developers to integrate with customized or third-party management applications.

This chapter contains the following sections:

• ANM Web Services API Overview, page 1-1

• Web Services Description Language, page 1-2

• Using the ANM Web Services API, page 1-3

ANM Web Services API OverviewANM Web Services provides APIs that support the operations for Application Control Engine (ACE) modules and appliances and Cisco Content Services Switch (CSS) and Cisco Content Switching Module (CSM) devices (for restrictive APIs) with all available releases. This API allows configuration functionalities.

ANM is a Java application that uses Java SE 6. Java SE 6 is a standard with Web Services support in the form of JSR 224, Java API for XML-Based Web Services (JAX-WS) 2.0. ANM makes use of Java SE 6 Web Services support to implement its Web Services-based NBI. Java SE 6 also supports JSR 181, Web Services Metadata for the Java Platform. JSR 181 makes it possible to develop web services. Additionally, Java SE 6 makes it extremely easy to publish a Java Web Service by using javax.xml ws.Endpoint of JAX-WS.

The ANM Web Services API is a Web Service implementation. Web Service is defined by the W3C standard as a software system designed to support interoperable machine-to-machine (client and server) interaction over the network. The client and server communication follows the Simple Object Access Protocol or Service Oriented Architecture Protocol (SOAP) standard.

SOAP, which exchanges XML-based messages over the network using HTTP or HTTPS, is the foundation layer of the Web Service stack. It provides a basic messaging framework that allows more abstract layers to build on. SOAP encoding wraps XML headers and tags in a SOAP envelope.

To call a service, you connect to a particular ANM through a web browser by using a service URL that contains the IP address or hostname of the ANM and the name of the particular service (such as OperationManager). For example, https://<host/ip>:8443/anm/OperationManager?wsdl is the service URL for the Operation Manager Service. By default, ANM 4.3 supports up to 10 concurrent sessions for web services (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).

1-1uide for Cisco Application Networking Manager 4.3

Chapter 1 Introduction to the Cisco ANM Web Services API Web Services Description Language

Next, you must post a SOAP request written in a XML format to retrieve the information. The request calls for a particular action (such as Login) and the input parameter content when required. The ANM responds with a SOAP envelope that contains the answer in an XML format. The response contains the output values for this action.

The following example shows an XML-formatted SOAP request to perform the Login action. There are no input parameters for this particular action.

Example Request <?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <login xmlns="http://anm.cisco.com"> <user xmlns="">admin</user> <password xmlns="">admin</password> </login> </SOAP-ENV:Body></SOAP-ENV:Envelope>

The following example shows the XML response that contains the output values for this action, such as the SessionToken.

Example Response <?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:loginResponse xmlns:ns2="http://anm.cisco.com"> <SessionToken xmlns=""> <sid>5546099606143734326</sid> </SessionToken> </ns2:loginResponse> </S:Body></S:Envelope>

Enabling the Web Services InterfaceAfter you have installed the ANM, you can reconfigure ANM configuration properties, such as enabling HTTP(S) for Web Services. For information about enabling Web Services, see the “Changing ANM Configuration Property Values” section in the User Guide for the Cisco Application Networking Manager 4.3.

Web Services Description LanguageIn the ANM Web Services API, Web Services Description Language (WSDL) is used with SOAP and XML schemas to provide Web Services. WSDL is an XML-based service that describes the functionality offered by the Web Service and defines the actions, parameter names, input parameter data types, and

1-2API Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01

http://www.cisco.com/en/US/docs/app_ntwk_services/data_center_app_services/application_networking_manager/4.3/user/guide/UG_trbl.html#wp1075902

http://www.cisco.com/en/US/docs/app_ntwk_services/data_center_app_services/application_networking_manager/4.3/user/guide/UG_trbl.html#wp1075902

Chapter 1 Introduction to the Cisco ANM Web Services API Using the ANM Web Services API

return data types for the Web Service. When you connect to a Web Service through a web browser, you can read the WSDL file to determine which functions are available on the server. Any special data types that are used are embedded in the WSDL file in an XML schema. You can then call one of the functions listed in the WSDL file by sending a SOAP request message.

To obtain the WSDL file defined for a particular service in the ANM Web Services API implementation, submit a URL to the service with a ?wsdl suffix. For example, to retrieve the WSDL for the OperationManager service running on https://localhost:8443/anm/OperationManager, call the WSDL file by using the following URL: https://<host/ip>:8443/anm/OperationManager?wsdl.

Using the ANM Web Services APIThis section describes how to use the ANM Web Services API. It contains the following topics:

• Required Software, Web Standards, and Supported Hardware, page 1-3

• Generating the Client Code to Invoke a Web Service, page 1-3

Required Software, Web Standards, and Supported HardwareThe Web Services API is supported in ANM 4.1 and later. The API examples in this document require the following development environment:

• Java SE 6

Note Java SE 6 is applicable only if the client code is java-based.

• WSDL Support: 1.1

• SOAP 1.1

The ANM Web Services API is supported on the following product types:

• Cisco Application Control Engine (ACE) module with ANM 4.1 and later.

• Cisco Application Control Engine (ACE) appliance with ANM 4.1 and later.

• Cisco Content Services Switch (CSS) with ANM 4.1 and later.

• Cisco Content Switching Module (CSM) and Cisco Content Switching Module with SSL (CSM-S) with ANM 4.1 and later.

• Cisco Global Site Selector (GSS) with ANM 4.3 and later.

Generating the Client Code to Invoke a Web ServiceTo generate the client source code, follow these steps:

Step 1 Download the WSDL file from the server using the following WSDL URL format:

https://<host/ip>:8443/anm/OperationManager?wsdl

or

http://<host/ip>:8080/anm/OperationManager?wsdl


OL-24855-01

Chapter 1 Introduction to the Cisco ANM Web Services API Using the ANM Web Services API

where the host/ip value is the hostname or IP address of the ANM that has the service running.

Step 2 Save the file as OperationManager.wsdl.

Step 3 Use the wsimport command to generate and compile the source code:

wsimport -d <specify where to place generated output files> -s <specify where to place generated source files> OperationManager.wsdl

The above command generates the java source code from the wsdl file and then compiles it and puts the class file in the same location where the source file .wsimport file is located in the dir $JAVA_HOME/bin.

Note This step is applicable only if the client code is a java-based code.


OL-24855-01


C H A P T E R 2
ANM Web Services API
This chapter describes the ANM Web Services API, which allows you to manage the Cisco Application Control Engine (ACE) module, Cisco Application Control Engine (ACE) appliance, Cisco Content Services Switch (CSS) and Cisco Content Switching Module (CSM), Cisco Content Switching Module with SSL (CSM-S), and Cisco Global Site Selector (GSS) using ANM. ANM Web Services provides APIs to support configuration functionalities. All APIs are implemented as synchronous calls and each call is a transaction.

This chapter contains the mapping table and describes the following ANM APIs:

• Mapping Table

• Login

• Logout

• listDeviceIDs

• listVirtualContexts

• listVirtualServers

• listServerfarms

• listRservers

• listServerfarmRservers

• listAnswers

• listDnsRules

• activateVirtualServer

• suspendVirtualServer

• addRserverToServerfarm

• removeRserverFromServerfarm

• activateServerfarmRserver

• suspendServerfarmRserver

• changeServerfarmRserverWeight

• activateAnswer

• suspendAnswer

• activateDnsRule

• suspendDnsRule


Chapter 2 ANM Web Services API Mapping Table

• getVMMappingInfo

Mapping TableTable 2-1 displays the mapping of each API with the specified role and the domain, where

• F = Full access

• N = No access

Table 2-1 Mapping Table

API Name

Role Name

ACE-A

dmin

AN

M-A

dmin

Netw

ork-Adm

in

Netw

ork-Monitor

Org-A

dmin

Security-Adm

in

Server-Appln-M

aintenance

Server-Maintenance

SLB-A

dmin

SSL-Adm

in

SSL-Cert-Key-Adm

in

VM-M

apper

listDeviceIDs N F N F F N N N N N N N

listVirtualContexts F F F F F N N N N N N N

listVirtualServers F F N F F N F F F N N N

listServerfarms F F N F F N F F F N N N

listRservers F F N F F N F F F N N N

listServerfarmRservers F F N F F N F F F N N N

listAnswers N F N N F N F F F N N N

listDnsRules N F N N F N F F F N N N

activateVirtualServer F F N N F N N N F N N N

suspendVirtualServer F F N N F N N N F N N N

addRserverToServerfarm F F N F F N F F F N N N

removeRserverFromServerfarm F F N N F N F N F N N N

activateServerfarmRserver F F N N F N F F F N N N

suspendServerfarmRserver F F N N F N F F F N N N

changeServerfarmRserverWeight F F N N F N F F F N N N

activateAnswer N F N N F N N F F N N N

suspendAnswer N F N N F N N F F N N N

activateDnsRule N F N N F N N F F N N N

suspendDnsRule N F N N F N N F F N N N

getVMMappingInfo N F N N F N N N N N N F


OL-24855-01

Chapter 2 ANM Web Services API Login

LoginThis request logs in an application user to ANM. Login API validates the credentials and returns a session token. The session times out after being idle for 30 minutes even if the logout is not called.By default, ANM allows 10 concurrent API logins, but you can modify this number (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the Login action. The input parameters for this particular action are username and password.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <login xmlns="http://anm.cisco.com"> <user xmlns="">admin</user> <password xmlns="">admin</password> </login> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response

Parameter Description

Username Username of the application user.

Password Password of the application user.


SessionToken Session key of the application user.

Type Exception String

String Maximum session limit [configured_limit] reached for WS.

Note The default is 10 (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).

String Invalid username or password. Please try again.

String Session ID is in use. Please try again later.

String Username cannot be null.

String Password cannot be null.


OL-24855-01

Chapter 2 ANM Web Services API Logout

Logout This request logs out an application user from the ANM. The session times out after being idle for 30 minutes even if the logout is not called. In case of a session timeout, the following exception string is generated: Invalid Session Id.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the Logout action. Session token is the input parameter for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <logout xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-6055365969690519291</sid> </sessionToken> </logout> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains no output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:logoutResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>




None None.


Integer Invalid Session ID.


OL-24855-01

Chapter 2 ANM Web Services API listDeviceIDs

listDeviceIDsThis request lists all DeviceIDs for a device type from the ANM inventory. If none of the devices is imported in ANM, it returns an empty list.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listDeviceIDs action. SessionToken and DeviceType are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listDeviceIds xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-81548021995146358</sid> </sessionToken> <deviceType xmlns="">VIRTUAL_CONTEXT</deviceType> </listDeviceIds> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains DeviceID as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listDeviceIdsResponse xmlns:ns2="http://anm.cisco.com"> <DeviceIDs xmlns="">



DeviceType List of device types including the device name and status. For example, CSS, CSM, CAT6K, GSS, VIRTUAL_CONTEXT, ACE4710, and ACE_BLADE.


DeviceIDs List of device IDs including the device name, device type, IP address, slot, and chassis IP address attributes.


String Invalid Session ID.

String Unsupported Device Type: “[device type].”

String Device Type should not be null.


OL-24855-01

Chapter 2 ANM Web Services API listDeviceIDs

<item> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </item> <item> <name>VC1</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </item> <item> <name>VC2</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </item> <item> <name>VC3</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </item> <item> <name>VC4</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </item> <item> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>3</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> <item> <name>VC1</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>3</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> <item> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>4</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> <item> <name>VC1</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>4</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> </DeviceIDs> </ns2:listDeviceIdsResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listVirtualContexts

listVirtualContextsThis request lists all the virtual contexts for an Application Control Engine (ACE) module or ACE appliance from the ANM inventory. This API is supported only on ACE modules and appliances (device type: ACE_BLADE and ACE4710).

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listVirtualContexts action. SessionToken and DeviceID are the input parameters for this particular action.



DeviceID For ACE module: The device ID including the device type, slot, and chassis IP address attributes.

For ACE appliance: The device ID including the device type, IP address, and name attributes.


DeviceIDs List of virtual context device IDs including the device type, IP address, slot, and chassis IP address attributes.



String Given ACE module is not yet imported in ANM.

String Given ACE Appliance does not exist in ANM.

String None of the devices are imported.


String Given ACE module does not exist in the chassis: “Chassis IP address.”

String Device Type should be not null.

String “chassisIPAddr” and “ipAddr” are not added in deviceID. Either should be provided.

String Both “chassisIPAddr” and “ipAddr” are added in deviceID. Only one of them can be added.

String DeviceID should not be not null.

String DeviceType is set as ACE_BLADE, but the mandatory field “slot” is set as null or empty.

String DeviceType is set as ACE4710, but the mandatory field “ipAddr” is set as null or empty.

String Invalid IP Address: “IP address.”

String DeviceType is set as ACE_BLADE, but the mandatory field “slot” is set as null or empty.


OL-24855-01

Chapter 2 ANM Web Services API listVirtualContexts

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listVirtualContexts xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-81548021995146358</sid> </sessionToken> <deviceIDs xmlns=""> <deviceType>ACE_BLADE</deviceType> <slot>3</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </deviceIDs> </listVirtualContexts> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains the list of virtual context DeviceIDs as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listVirtualContextsResponse xmlns:ns2="http://anm.cisco.com"> <DeviceIDs xmlns=""> <item> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>3</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> <item> <name>VC1</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>3</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </item> </DeviceIDs> </ns2:listVirtualContextsResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listVirtualServers

listVirtualServersThis request lists all the virtual servers configured on the specified device. The device can be a CSS, CSM, or a virtual context (VIRTUAL_CONTEXT) on an ACE module or ACE appliance (device type: ACE_BLADE and ACE4710).

Input Parameters

Output Parameters

Exceptions



DeviceID Virtual context DeviceID, which contains the virtual server name, device type, IP address, chassis slot, and chassis IP address attributes.

allVSs (Optional) Input parameter that instructs ANM to return a list of all virtual servers that match ANM’s virtual server definition and those that do not match this definition but that ANM can recognize as virtual servers using SNMP polling. By default, ANM returns only the virtual servers that match ANM’s virtual server definition.


vservers List of all virtual servers including the virtual server name, policy-map name, and IP address attributes.




Note The default is 10 (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).










String DeviceType is set as VIRTUALCONTEXT, but the mandatory field “slot” is set as null or empty.


OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the listVirtualServers action. SessionToken, DeviceID, and allVSs are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listVirtualServers xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>7299761084673772498</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr/> <slot>2</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </deviceID> <allVS xmlns="">false</allVS> </listVirtualServers> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains the list of virtual servers as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listVirtualServersResponse xmlns:ns2="http://anm.cisco.com"> <listVirtualServers xmlns=""> <item> <virtualserverName>14_simple_vs</virtualserverName> <policyMapName>int2</policyMapName>

String DeviceType is set as VIRTUALCONTEXT, but the mandatory field “name” is set as null or empty.

String Invalid IP Address: “[IP address].”

String Given virtual context name “[VC name]” does not exist in the ACE Devices.

String DeviceType is set as CSS, but the mandatory field “ipAddr” is set as null or empty.

String DeviceType is set as VIRTUAL_CONTEXT, but the mandatory field “ipAddr” is set as null or empty.

String Device Type is set as CSM, but the mandatory field “chassisIPAddr” is set as null or empty.

String Device Type is set as CSM, but the mandatory field “slot” is set as null or empty.


OL-24855-01


<matchConditions> <ipAddress>15.5.3.2</ipAddress> <protocol>tcp</protocol> <port>2</port> </matchConditions> <serverfarms>14_simple_sf</serverfarms> <vlans>2</vlans> <adminState>DOWN</adminState> <operState>DOWN</operState> <lastPolledTime>Fri May 27 16:52:31 IST 2011</lastPolledTime> </item> <item> <virtualserverName>ds_simple_vs</virtualserverName> <policyMapName>int161</policyMapName> <matchConditions> <ipAddress>13.3.3.3</ipAddress> <protocol>tcp</protocol> <port>6</port> </matchConditions> <serverfarms>ds_simple_sf</serverfarms> <vlans>161</vlans> <adminState>DOWN</adminState> <operState>DOWN</operState> <lastPolledTime>Fri May 27 16:52:31 IST 2011</lastPolledTime> </item> <item> <virtualserverName>test</virtualserverName> <policyMapName>global</policyMapName> <matchConditions> <ipAddress>4.5.6.7</ipAddress> <protocol>tcp</protocol> <port>443</port> </matchConditions> <serverfarms>gh</serverfarms> <vlans/> <adminState>UP</adminState> <operState>DOWN</operState> <lastPolledTime>Fri May 27 16:52:31 IST 2011</lastPolledTime> </item> </listVirtualServers> </ns2:listVirtualServersResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listServerfarms

listServerfarmsThis request lists all the server farms on a virtual context from the ANM inventory. This API is supported only on ACE devices (device type: VIRTUAL_CONTEXT).

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listServerfarms action. SessionToken and DeviceID are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?>



DeviceID Virtual context device ID including the device name, device type, IP address, slot, and chassis IP address attributes.


Serverfarms List of server farm objects including the name and type (host or redirect) attributes.




The default is 10 (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).















OL-24855-01

Chapter 2 ANM Web Services API listServerfarms

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listServerFarms xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>8368662778638735743</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> </listServerFarms> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains the list of Serverfarm objects as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listServerFarmsResponse xmlns:ns2="http://anm.cisco.com"> <serverfarms xmlns=""> <item> <name>SF1</name> <serverFarmType>host</serverFarmType> </item> <item> <name>SF2</name> <serverFarmType>host</serverFarmType> </item> </serverfarms> </ns2:listServerFarmsResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listRservers

listRserversThis request lists all the real servers on a virtual context from the ANM inventory. This API is supported only on ACE devices (device type: VIRTUAL_CONTEXT).

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listRservers action. SessionToken and DeviceID are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?>





Rservers List of real server objects including the name, IP address, admin state, and weight attributes.






String Given ACE appliance does not exist in ANM.











String Given virtual context name “[VC name]” does not exist in the ACE devices.


OL-24855-01

Chapter 2 ANM Web Services API listRservers

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listRservers xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>8368662778638735743</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> </listRservers> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains the list of real server objects as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listRserversResponse xmlns:ns2="http://anm.cisco.com"> <Rservers xmlns=""> <item> <name>RS1</name> <type>host</type> <state>IS</state> <weight>8</weight> </item> <item> <name>RS2</name> <type>redirect</type> <state>IS</state> </item> </Rservers> </ns2:listRserversResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listServerfarmRservers

listServerfarmRserversThis request lists all the real servers present in the given server farm from the ANM inventory. If the server farm name is provided as empty or null in the input parameters, it lists all the real server objects in the given virtual context. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM, and VIRTUAL_CONTEXT).

Input Parameters

Output Parameters

Exceptions



DeviceID Device ID of the virtual context including the device name, device type, IP address, slot and chassis IP address attributes.

Serverfarmname Name of an existing server farm. It can be empty, null, or a specific server farm configured in the device.


SfRservers List of server farm real server objects including server farm name, server farm real server name, IP address, admin state, weight, and port value attributes.


String Invalid session ID.




String Given ACE appliance does not exist in ANM.













OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the listServerfarmRservers action. SessionToken, DeviceID, and Serverfarmname are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listServerfarmRservers xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-2221649013806878130</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <serverfarmname xmlns="">SF1</serverfarmname> </listServerfarmRservers> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains SfRserver as the output parameter:

<S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:listServerfarmRserversResponsexmlns:ns2="http://anm.cisco.com"><SfRservers xmlns=""><item><serverfarmName>SF1</serverfarmName><realserverName>04122009sanitytesting</realserverName><adminState>IS</adminState><operationState>UP</operationState><weight>8</weight><port>0</port><lastPolledTime>Wed Jun 08 20:53:18 IST 2011</lastPolledTime></item><item><serverfarmName>1</serverfarmName><realserverName>anm-vm-118</realserverName><adminState>IS</adminState>






OL-24855-01


<weight>19</weight><port>0</port></item><item><serverfarmName>SF1</serverfarmName><realserverName>test</realserverName><adminState>OOS</adminState><operationState>UP</operationState><weight>8</weight><port>443</port><ipAddr>10.2.1.11</ipAddr><lastPolledTime>Wed Jun 08 20:53:18 IST 2011</lastPolledTime></item></SfRservers></ns2:listServerfarmRserversResponse></S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listAnswers

listAnswersThis request lists all the VIP answers configured on the specified given GSS.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listAnswers action. SessionToken and DeviceID are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listAnswers xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>7299761084673772498</sid> </sessionToken> <deviceID xmlns=""> <name>GSS</name> <deviceType>GSS</deviceType> <ipAddr>172.23.244.135</ipAddr> <slot>0</slot> <chassisIPAddr/> </deviceID> </listAnswers> </SOAP-ENV:Body></SOAP-ENV:Envelope>



DeviceID GSS device ID, which contains the GSS name, device type, and IP address attributes.


answers List of answer objects, including the answer name, IP address, configuration state, and type attributes. The type attribute is always “vip.”


String Invalid session token.

String GSS does not exist.

String Session timeout.

String Cannot reach the GSS.


OL-24855-01

Chapter 2 ANM Web Services API listAnswers

Example Response The following example shows the XML response that contains answers as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listAnswersResponse xmlns:ns2="http://anm.cisco.com"> <Answers xmlns=""> <item> <ipAddr>10.10.9.99</ipAddr> <answerName>vip2131</answerName> <type>null</type> <configState>ACTIVATE</configState> <anserGroups>vipgrp1066</anserGroups> <location>null</location>

<device>GSS</device> <operState>ACTIVE</operState> <pGssmTime>17:50:19</pGssmTime> </item> </DeviceIDs> </ns2:listAnswersResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API listDnsRules

listDnsRulesThis request lists all the DNS rules configured on the specified given GSS.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the listDnsRules action. SessionToken and DeviceID are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <listDnsRules xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>6600024266770332702</sid> </sessionToken> <deviceID xmlns=""> <name>40</name> <deviceType>GSS</deviceType> <ipAddr>10.77.241.40</ipAddr> </deviceID> </listDnsRules> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that contains dnsRules as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope



DeviceID GSS device ID, which contains the GSS name, device type, and IP address attributes.


dnsRules List of DNS rule objects, including the DNS rule name, source IP address, owner, and configuration state attributes.







OL-24855-01

Chapter 2 ANM Web Services API listDnsRules

xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:listDnsRulesResponse xmlns:ns2="http://anm.cisco.com"> <listDnsRules xmlns=""> <item> <dnsRuleName>dns1</dnsRuleName> <sourceAddress>Anywhere</sourceAddress> <domains>dom1</domains> <dnsConfigState>Active</dnsConfigState> <answerGroups>null</answerGroups> <owner>System</owner> </item> </listDnsRules> </ns2:listDnsRulesResponse> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API activateVirtualServer

activateVirtualServerThis request activates an existing virtual server, putting it into service. This API is supported on CSS, CSM, and virtual contexts (VIRTUAL_CONTEXT) on ACE modules and appliances.

Note For CSS and CSM devices, after changing the state, SNMP polling is triggered. The API does not return until the polling is complete.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the activateVirtualServer action. SessionToken, DeviceID, and virtualServer (vip1) are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <activateVirtualServer xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>2713248117084982682</sid> </sessionToken> <deviceID xmlns="">



DeviceID Virtual server device ID, including the device name, device type, IP address, slot, and chassis IP address attributes.

Vserver Virtual server object, including the virtual server name, policy-map name, and IP address attributes.

Reason Reason for the activation.


None None.



String Virtual context does not exist.


String Cannot reach the virtual context.

String Virtual server does not exist.

String Config errors from the ACE, CSS, or CSM.


OL-24855-01

Chapter 2 ANM Web Services API activateVirtualServer

<name>SysTestApp</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>2</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </deviceID> <vserver xmlns=""> <virtualserverName>12_simple_vs</virtualserverName> <policyMapName>NAT_Policy</policyMapName> </vserver> <reason xmlns="">testing</reason> </activateVirtualServer> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:activateVirtualServerResponse xmlns:ns2="http://anm.cisco.com"/></S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API suspendVirtualServer

suspendVirtualServerThis request suspends an existing virtual server, putting it out of service. This API is supported on CSS, CSM, and virtual contexts (VIRTUAL_CONTEXT) on ACE modules and appliances.


Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the suspendVirtualServer action. SessionToken, DeviceID, and virtualServer (vip1) are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <suspendVirtualServer xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>2713248117084982688</sid> </sessionToken> <deviceID xmlns="">



DeviceID Virtual server device ID, including the device name, device type, IP address, slot, and chassis IP address attributes.

Vserver Virtual server object, including the virtual server name, policy-map name, and IP address attributes.



None None.



String Virtual context does not exist.


String Cannot reach the virtual context.

String Virtual server does not exist.

String Config errors from the ACE, CSS, or CSM.


OL-24855-01

Chapter 2 ANM Web Services API suspendVirtualServer

<name>SysTestApp</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr/> <slot>2</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </deviceID> <vserver xmlns=""> <virtualserverName>12_simple_vs</virtualserverName> <policyMapName>NAT_Policy</policyMapName> </vserver> <reason xmlns="">test</reason> </suspendVirtualServer> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelopexmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns2:suspendVirtualServerResponse xmlns:ns2="http://anm.cisco.com"/></S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API addRserverToServerfarm

addRserverToServerfarmThis request adds a real server to an existing server farm. If it does not find the real server, it creates a real server and adds it to the server farm. This API is supported on ACE devices (device type: ‘VIRTUAL_CONTEXT’).

Input Parameters

Output Parameters

Exceptions



DeviceID Device ID of the virtual context including the device name, device type, IP address, slot and chassis IP address attributes.

Rserver Real server object including name, IP address, admin state, and weight attributes.

Port Port of the server farm real server.

Serverfarm Name of an existing server farm.


None None.













String “chassisIPAddr” and “ipAddr” are not added in device ID. Either should be provided.

String Both “chassisIPAddr” and “ipAddr'” are added in device ID. Only one of them can be added.




OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the addRserverToServerfarm action. SessionToken, DeviceID, Rserver, Port, and Serverfarm are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <addRserverToServerfarm xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>5731694438459731003</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <serverfarmname

String Given Server Farm “ServerFarmname” is not available in the given Virtual Context.

String Server Farm name should not be null or empty.



String Given Name: “ServerFarmname” exceeds the maximum length of 64 characters.

String Invalid Port: “Port Number.” Port number should be numeric.

String Invalid port value: “Port Number.” Port value is outside the range <0-65535>.

String Invalid weight value: “weight value.” Weight value should be numeric.

String Invalid weight value: “weight value.” Weight value is outside the range <0-100>.

String Invalid Name: “ServerFarmname.”.Name should match the format [^a-zA-Z0-9._-].

String Invalid Name: “RealServername.” Name should match the format [^a-zA-Z0-9._-].

String Invalid Name: “ServerFarmname.” Name should not hold any reserved keywords.

String Invalid Name: “RealServername.” Name should not hold any reserved keywords.

String IP address must be provided for the Real Server.

String Given Real Server type “Real Server Type” is not associated with Server Farm type “Server Farm type.”

String Real Server “Real Server Name/ Port value” already exist in the Server Farm “Server Farm name.”


OL-24855-01


xmlns="">SF1</serverfarmname> <rserver xmlns=""> <name>sampletest</name> <type>host</type> <ipAddr>2.3.6.53</ipAddr> <state>IS</state> <weight>34</weight> </rserver> <port xmlns="">0</port> </addRserverToServerfarm> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example Response The following example shows the XML response that has no output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:addRserverToServerfarmResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API removeRserverFromServerfarm

removeRserverFromServerfarmThis request removes an existing server farm real server from a server farm. It removes the real server, if there is no server farm real server reference to the real server. This API is supported on ACE devices (device type: VIRTUAL_CONTEXT).

Input Parameters

Output Parameters

Exceptions




SfRserver Server farm real server object including the server farm name, real server name, IP address, admin state, weight, and port attributes.


None None.




















OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the removeRserverFromServerfarm action. SessionToken, DeviceID, and SfRserver are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <removeRserverFromServerfarm xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-81548021995146358</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <rserver xmlns=""> <serverfarmName>SF1</serverfarmName> <realserverName>sampletest</realserverName> <adminState>IS</adminState> <weight>0</weight> <port>0</port> <ipAddr>2.3.6.53</ipAddr>


String Server Farm name should not be null or empty.

String Given Name : “ServerFarmname” exceeds the maximum length of 64 characters.



String Invalid weight value: “weight value.” Weight value should be numeric.

String Invalid weight value: “weight value.” Weight value is outside the range <0-100>.

String Invalid Name: “ServerFarmname.” Name should match the format [^a-zA-Z0-9._-].

String Invalid Name: “RealServername.” Name should match the format [^a-zA-Z0-9._-].

String Invalid Name: “ServerFarmname.” Name should not hold any reserved keywords.

String Invalid Name: “RealServername.” Name should not hold any reserved keywords.


String Given Real Server “ Real server name/ port value” does not exist in the Server Farm “Server Farm name.”


OL-24855-01


</rserver> </removeRserverFromServerfarm> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:removeRserverFromServerfarmResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API activateServerfarmRserver

activateServerfarmRserverThis request activates an existing server farm real server in service. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM and VIRTUAL_CONTEXT).


Input Parameters

Output Parameters

Exceptions




SfRserver Server farm real server object including the server farm name, real server name, IP address, admin state, weight and port attributes



None None.



String Server Farm name cannot be null.



String Given Server farm Real Server name cannot be null.

String Given Real Server state cannot be null.

String Given Real server weight cannot be null.

String Server Farm Real server port value should not be null.



String Given Cat6k does not exist in ANM.


String Given CSM does not exist in the chassis: “Chassis IP address.”

String Given CSS does not exist in ANM.



String Device Type should be null.


OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the activateServerfarmRserver action. SessionToken, DeviceID, SfRserver, and Reason are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <activateServerfarmRserver xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-5217915770163489503</sid> </sessionToken> <deviceID xmlns="">



String DeviceID should not be null.














String Given Real Server “Real server name/ port value” does not exist in the Server Farm “Server Farm name.”


OL-24855-01


<name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <rserver xmlns=""> <serverfarmName>SF1</serverfarmName> <realserverName>test</realserverName> <adminState>OOS</adminState> <weight>44</weight> <port>443</port> <ipAddr>10.2.1.11</ipAddr> </rserver> <reason xmlns="">sample Webservices testing</reason> </activateServerfarmRserver> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:activateServerfarmRserverResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API suspendServerfarmRserver

suspendServerfarmRserverThis request suspends the existing server farm real server. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM and VIRTUAL_CONTEXT).


Input Parameters

Output Parameters

Exceptions




SfRserver Server farm real server object including the server farm name, real server name, IP address, admin state, weight and port attributes

State List of options supported are Graceful, Suspend, Suspend_Clear_Connections.

Reason Reason for suspension.


None None.


















OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the suspendServerfarmRserver action. SessionToken, DeviceID, SfRserver, Reason, and State are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <suspendServerfarmRserver xmlns="http://anm.cisco.com"> <sessionToken


















String Invalid port value: “Port Number” Port value is outside the range <0-65535>.


String Invalid suspend state: “[suspend state].”


OL-24855-01


xmlns=""> <sid>2658073681808034239</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <rserver xmlns=""> <serverfarmName>SF1</serverfarmName> <realserverName>test</realserverName> <adminState>IS</adminState> <weight>44</weight> <port>443</port> <ipAddr>10.2.1.11</ipAddr> </rserver> <suspendState xmlns="">Suspend</suspendState> <reason xmlns=""/> </suspendServerfarmRserver> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:suspendServerfarmRserverResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API changeServerfarmRserverWeight

changeServerfarmRserverWeightThis request changes the weight of an existing server farm real server. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM, and VIRTUAL_CONTEXT).

Note For CSS & CSM devices, after changing the weight, SNMP polling is triggered. The API does not return until the polling is complete.

Input Parameters

Output Parameters

Exceptions




SfRserver Server farm real server object including the server farm name, real server name, IP address, admin state, weight and port attributes.

Reason Reason for the operation.


None None.




















OL-24855-01







String Invalid IP Address: “Ip address.”







String Given Name: “ServerFarmname” exceeds the maximum length of 15 characters

String Given Name : “ServerFarmname” exceeds the maximum length of 31 characters.


String Invalid port value: “Port Number.” .Port value is outside the range <0-65535>.




String Given Real Server “ Real server name/ port value” does not exist in the Server Farm “Server Farm name.”

String Invalid weight value: “weight value.” Weight value is outside the range <1-100> [ace module, ace appliance].

String Invalid weight value: “weight value.” Weight value is outside the range <0-100> [csm].

String Invalid weight value: “weight value.” Weight value is outside the range <0-10> [css].


OL-24855-01


Example Request The following example shows an XML-formatted SOAP request to perform the changeServerfarmRserverWeight action. SessionToken, DeviceID, SfRserver, and Reason are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <changeServerfarmRserverWeight xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>-5217915770163489503</sid> </sessionToken> <deviceID xmlns=""> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <rserver xmlns=""> <serverfarmName>SF1</serverfarmName> <realserverName>test</realserverName> <adminState>OOS</adminState> <weight>44</weight> <port>443</port> <ipAddr>10.2.1.11</ipAddr> </rserver> <reason xmlns=""/> </changeServerfarmRserverWeight> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:changeServerfarmRserverWeightResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API activateAnswer

activateAnswerThis request activates an existing answer on the specified GSS, putting the answer into service.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the activateAnswer action. SessionToken, DeviceID, and answer are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <activateAnswer xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>991427603955168471</sid> </sessionToken> <deviceID xmlns=""> <name>172.23.244.135</name> <deviceType>GSS</deviceType> <ipAddr>172.23.244.135</ipAddr> </deviceID> <answer xmlns=""> <ipAddr>2.3.4.5</ipAddr> <answerName>vip1</answerName> </answer>



DeviceID GSS device ID, including the device name, device type, and IP address attributes.

answer Answer object, including the answer name, IP address, and type attributes. The type is always “vip.”



None None.






String Config errors from the GSS.


OL-24855-01

Chapter 2 ANM Web Services API activateAnswer

<reason xmlns="">test</reason> </activateAnswer> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:activateAnswerResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API suspendAnswer

suspendAnswerThis request suspends an existing answer on the specified GSS, putting the answer out of service.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the suspendAnswer action. SessionToken, DeviceID, and answer are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <suspendAnswer xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>991427603955168481</sid> </sessionToken> <deviceID xmlns=""> <name>172.23.244.135</name> <deviceType>GSS</deviceType> <ipAddr>172.23.244.135</ipAddr> </deviceID> <answer xmlns=""> <ipAddr>2.3.4.5</ipAddr> <answerName>vip1</answerName> </answer>




answer Answer object, including the answer name, IP address, and type attributes. The type is always “vip.”



None None.








OL-24855-01

Chapter 2 ANM Web Services API suspendAnswer

<reason xmlns="">test</reason> </suspendAnswer> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:suspendAnswerResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API activateDnsRule

activateDnsRuleThis request activates an existing DNS rule on the specified GSS, putting the DNS rule into service.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the activateDnsRule action. SessionToken, DeviceID, and dnsRule are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <activateDnsRule xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>6195441786283682375</sid> </sessionToken> <deviceID xmlns=""> <name>172.23.244.135</name> <deviceType>GSS</deviceType> <ipAddr>172.23.244.135</ipAddr> </deviceID> <dnsrule xmlns=""> <dnsRuleName>dns1</dnsRuleName> <sourceAddress>Anywhere</sourceAddress> </dnsrule>




dnsRule DNS rule object, including the DNS rule name, source IP address, owner, and configuration state attributes.



None None.








OL-24855-01

Chapter 2 ANM Web Services API activateDnsRule

<reason xmlns="">test</reason> </activateDnsRule> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:activateDnsRuleResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API suspendDnsRule

suspendDnsRuleThis request suspend an existing DNS rule on the specified GSS, putting the DNS rule out of service.

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the suspendDnsRule action. SessionToken, DeviceID, and dnsRule are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <suspendDnsRule xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>6195441786283682370</sid> </sessionToken> <deviceID xmlns=""> <name>172.23.244.135</name> <deviceType>GSS</deviceType> <ipAddr>172.23.244.135</ipAddr> </deviceID> <dnsrule xmlns=""> <dnsRuleName>dns1</dnsRuleName> <sourceAddress>Anywhere</sourceAddress> </dnsrule>




dnsRule DNS rule object, including the DNS rule name, source IP address, owner, and configuration state attributes.



None None.








OL-24855-01

Chapter 2 ANM Web Services API suspendDnsRule

<reason xmlns="">test</reason> </suspendDnsRule> </SOAP-ENV:Body></SOAP-ENV:Envelope>


<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:suspendDnsRuleResponse xmlns:ns2="http://anm.cisco.com"/> </S:Body></S:Envelope>


OL-24855-01

Chapter 2 ANM Web Services API getVMMappingInfo

getVMMappingInfoThis request returns all the server farm real server mapping information for a given VM. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM, and VIRTUAL_CONTEXT).

Input Parameters

Output Parameters

Exceptions

Example Request The following example shows an XML-formatted SOAP request to perform the getVMMappingInfo action. SessionToken and VMName are the input parameters for this particular action.

<?xml version="1.0" encoding="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <SOAP-ENV:Body> <getVMMappingInfo xmlns="http://anm.cisco.com"> <sessionToken xmlns=""> <sid>3920090311151112722</sid> </sessionToken> <vmname xmlns="">/Vcenter/ANM_DC/vm/Discovered virtual machine/anm-vm-115</vmname> </getVMMappingInfo> </SOAP-ENV:Body></SOAP-ENV:Envelope>



VMName Unique name of the VM. The format is “/<Vcenter Name given in ANM>/<full path for vmname as in the Vcenter>/<VM name>”.


VMMappingInfos Object attributes including the device ID, server farm name, server farm real server name, IP address, and port attributes.


String Invalid session ID.



String None of the vCenter is imported in ANM.

String Given VM “[VM name]” does not exist.

String Unable to get DeviceId for “[deviceid].”

String Vmname should not be null.


OL-24855-01


Example Response The following example shows the XML response that contains the list of VMMappingInfo objects as the output parameter:

<?xml version="1.0" encoding="UTF-8"?><S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns2:getVMMappingInfoResponse xmlns:ns2="http://anm.cisco.com"> <VMMappingInfos xmlns=""> <item> <deviceID> <deviceType>CSS</deviceType> <ipAddr>172.23.244.250</ipAddr> </deviceID> <sfname>myReal8</sfname> <sfrsname>myReal8</sfrsname> <port>0</port> <ipaddr>0.0.0.0</ipaddr> </item> <item> <deviceID> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <slot>4</slot> <chassisIPAddr>10.77.247.2</chassisIPAddr> </deviceID> <sfname>WEB-SF</sfname> <sfrsname>webservicesample</sfrsname> <port>0</port> <ipaddr>3.3.3.4</ipaddr> </item> <item> <deviceID> <deviceType>CSM</deviceType> <slot>4</slot> <chassisIPAddr>172.23.244.130</chassisIPAddr> </deviceID> <sfname>FOO2</sfname> <sfrsname>RS1</sfrsname> <port>0</port> <ipaddr/> </item> <item> <deviceID> <name>Admin</name> <deviceType>VIRTUAL_CONTEXT</deviceType> <ipAddr>10.77.241.46</ipAddr> </deviceID> <sfname>tst_sf_dup</sfname> <sfrsname>testing_dup</sfrsname> <port>0</port> </item> </VMMappingInfos> </ns2:getVMMappingInfoResponse> </S:Body></S:Envelope>


OL-24855-01



OL-24855-01


C H A P T E R 3
Web Service Objects
This chapter describes the data types that are defined structures or objects in the ANM Web Services API. Web Service objects perform the following functions:

• Parse input parameters and validate their values

• Invoke the appropriate ANM function

• Assemble the returned result and pass it to the SOAP endpoint

• Handle exceptions from the ANM by reporting the error to the client

This chapter describes the following Web Service objects:

• DeviceID

• Vserver

• Serverfarm

• Rserver

• SfRserver

• Answer

• DnsRule

• VMMappingInfo


Chapter 3 Web Service Objects DeviceID

DeviceIDThis section lists and describes the DeviceID object attributes and Table 3-1 lists the mandatory attributes for each device type.

Note The optional attributes are indicated by the dash (—).

Attribute Description

name String value that contains virtual context name.

deviceType String value that contains the device type.

ipAddress String value that contains the device IP address.

slot String value that contains the device slot.

chassisIPAddr String value that contains the chassis IP address.

Table 3-1 Mandatory Attributes for a Device Type

DeviceType name chassisIpaddr Ipadddr slot

ACE Appliance

ACE4710 — — Appliance IP address

—

ACE Appliance Virtual Context

VIRTUAL_CONTEXT

VC Name — Appliance IP address

—

ACE Module ACE_BLADE — Chassis IP address

— ACE Module slot

ACE Module Virtual Context

VIRTUAL_CONTEXT

VC Name Chassis IP address

— ACE Module slot

CSS CSS — — CSS IP address

—

CSM CSM — Chassis IP address

— CSM Module slot

Chassis CAT_6_K — Chassis IP address

— —


OL-24855-01

Chapter 3 Web Service Objects Vserver

VserverThis section lists and describes the Vserver object attribute.

ServerfarmThis section lists and describes the Serverfarm object attributes.

RserverThis section lists and describes the Rserver object attributes.


virtualserverName String value that contains the virtual name.


name String value that contains the server farm name.

serverFarmType String value that contains the server farm type.


name String value that contains the real server name.

type String value that contains the real server type.

ipAddress String value that contains the real server IP address.

state String value that contains the real server state.

weight String value that contains the real server weight.


OL-24855-01

Chapter 3 Web Service Objects SfRserver

SfRserverThis section lists and describes the SfRserver object attributes.

AnswerThis section lists and describes the Answer object attributes.

DnsRuleThis section lists and describes the DnsRule object attributes.

VMMappingInfoThis section lists and describes the VMMappingInfo object attributes.


serverfarmName String value that contains the server farm name.

adminState String value that contains the SfRserver admin state.

weight String value that contains the SfRserver weight.

port String value that contains the SfRserver port.

realserverName String value that contains the real server name.

ipAddress String value that contains the real server IP address.


name String value that contains the answer name.

AnswerType String value that contains the answer type.


name String value that contains the DNS rule name.

DnsRuleType String value that contains the DNS rule type.


Sfrserver String value that contains SfRserver Web Service object.

deviceID String value that contains deviceID Web Service object.


OL-24855-01


C H A P T E R 4
Troubleshooting Problems
This chapter describes how to troubleshoot problems with Cisco Application Networking Manager (ANM) and includes the following sections:

• SOAP Message Traffic and Time Taken to Invoke an API, page 4-1

• Custom Application Errors, page 4-1

• Modifying the Number of Concurrent Sessions Allowed, page 4-3

SOAP Message Traffic and Time Taken to Invoke an APITo see the SOAP messages passed to and from the ANM, enable the debug for ANM Web Services and check the corresponding logs.

Procedure

Step 1 Go to the cs-config.properties file, located in the following directory:

/opt/CSCOanm/etc

Step 2 Change the value of ws.debug to “true” as follows:

ws.debug=true

Step 3 Restart the ANM server by entering the following command:

/opt/CSCOanm/bin/anm-tool restart

Enabling the debug creates a log file named as webservices.log under the /var/lib/anm/logs directory. The log file contains details of both inbound and outbound SOAP messages.

Custom Application ErrorsWorkarounds for the errors you may encounter are as follows:

• DeviceType is set as deviceTypeValue, but mandatory field 'fieldName' is set as null or empty’.

Cause: The mandatory attributes are not set for the DeviceID. For each device type, a certain set of attributes are mandatory to uniquely identify the device on the ANM.


Chapter 4 Troubleshooting Problems Custom Application Errors

Solution: Set the mandatory fields for each device type in the DeviceID. See the “DeviceID” section on page 3-2 for the complete list of mandatory fields for each device type.

• Maximum session limit [configured_limit] reached for WS

Cause: The number of open Web Service sessions permitted on ANM has reached the configured maximum value (default = 10).

Solution1: Close the session by invoking the following API:

OperationManager: logout(sessionToken)

Note You can modify the number of concurrent sessions permitted (see the “Modifying the Number of Concurrent Sessions Allowed” section on page 4-3).

Solution2: Wait until the sessions are automatically logged out from the ANM. By default, the sessions are logged out after an idle period of 30 minutes.

• Session ID is in use and the operation has not been completed. Please try again later once the operation has completed

Cause: The session token used to invoke the API is already used to invoke some other API that is still engaged. Once a session token is used to invoke an API, the session token cannot be used unless the previously invoked API completes its operation.

Solution: Wait until the previously invoked API completes its operation.

• Invalid ‘Session ID’

Cause: The session token being used in the API has timed out or some unknown session ID is in use.

Solution: None. Use login() API to create a session ID and use the new session ID.

• Unsupported Device Type: “[Device Type]”

Cause: The API is supported only for a certain device type. This system message appears if an API is invoked with an unsupported device type.

Solution: Use the API only for the supported device type. The complete list of supported device type for each API is displayed in the Mapping Table, page 2-2.

• Given ACE module does not exist in the chassis: “Chassis Ip address”

Cause: The incorrect slot information is given in the DeviceID.

Solution: Check and correct the slot number or chassis IP address configured in the DeviceID.

• Given ACE module is not yet imported in ANM

Cause: The ACE module with the given slot is available but it is not yet imported in ANM.

Solution: Correct the slot number in the DeviceID or log in to ANM and import the ACE module.

• Given Virtual context name “[VCName]” does not exist in the ACE Devices

Cause: The incorrect or non-existent Virtual Context is given in the DeviceID.

Solution: Check that the VC given in the DeviceID exists in the ACE module or ACE appliance.

• Given ‘<device model>’ does not exist in ANM

Cause: The specified device is not yet imported into the ANM.

Solution: Check if the correct IP address is configured in the DeviceID. Or log in to ANM and import the corresponding device.


OL-24855-01

Chapter 4 Troubleshooting Problems Modifying the Number of Concurrent Sessions Allowed

Modifying the Number of Concurrent Sessions AllowedBy default, ANM supports up to 10 concurrent sessions for web services and any session that is left idle for 30 minutes will time out. You can modify the maximum number of concurrent sessions allowed.

Note Having more than 10 sessions open at the same time can slow the performance of ANM.

Procedure

Step 1 Open the following properties file in a text editor:

/opt/CSCOanm/etc/cs-config.properties

Step 2 From the text editor, add the following line to the cs-config.properties file:

ws.max.concurrentsessions=number

where number is the maximum number of concurrent connections allowed.

Step 3 Save the modified cs-config.properties file.

Step 4 Restart the ANM services by entering the following command

/opt/CSCOanm/bin/anm-tool restart-services


OL-24855-01

Chapter 4 Troubleshooting Problems Modifying the Number of Concurrent Sessions Allowed


OL-24855-01

API Reference Guide foOL-24855-01

A
P P E N D I X A Use Case Examples
This chapter lists the use case sample code examples, and includes the following sections:

• Use Case 1: SampleWSClient, page A-1

• Use Case 2: ActivateSuspendSfRserverClient, page A-5

• Use Case 3: Virtual Server WS Client, page A-10

• Use Case 4: GSSWSClient, page A-17

Use Case 1: SampleWSClientThe following example shows a java-based sample code to list the server farm or real servers on the ANM. After you import the ACE into the ANM, you can call the ANM Web Services API to get the list of ACE DeviceIDs and for each device ID, it displays the virtual context device IDs, and then for each context it displays the server farm and server farm real servers within the server farm:

/** * Title: SampleWSClient * Description: Sample WS client code using java. It lists the devices imported in ANM, the Virtual * Contexts and the serverfarms/realservers configured in it. * Copyright: Copyright(C) 2010 Cisco Systems. All Rights Reserved. * Company: Cisco Systems * @author: kamachan, Aug 2010 * @version: 1.0 */package com.cisco.anm.client;

import java.io.IOException;import java.lang.reflect.Constructor;import java.lang.reflect.Method;import java.net.URL;import java.util.List;

import javax.xml.namespace.QName;import javax.xml.ws.BindingProvider;import javax.xml.ws.Service;

import com.cisco.anm.DeviceID;import com.cisco.anm.DeviceIDArray;import com.cisco.anm.DeviceType;import com.cisco.anm.OperationManager;import com.cisco.anm.Serverfarm;import com.cisco.anm.ServerfarmArray;

A-1r Cisco Application Networking Manager 4.3

Appendix A Use Case Examples Use Case 1: SampleWSClient

import com.cisco.anm.SessionToken;import com.cisco.anm.SfRserver;import com.cisco.anm.SfRserverArray;

/** * @author kamachan * * Sample code to print all the serverfarms/realservers configured in all imported ACE modules and appliances. * This code illustrate a basic usage of ANM WS code to get the ACE module/appliance deviceid and its virtual context * deviceid and then using the deviceid, it gets the list of serverfarms/realservers configured in the deviceid. * * Prerequiste: * To compile the file, include the stubs generated from the wsdl file. It is already packed in a jar (????) file - dcm-ws-client-<version>.jar ???? * * */public class SampleWSClient { static final String NAMESPACE = "http://anm.cisco.com"; static String URL_TEMPLATE = "%s://%s:%s/anm/%s"; // <protocol>://<IPAddress>:<Port>/anm/<service name> static final String WS_NAME = "OperationManager"; public static BindingProvider getPort(String ws, String protocol, String host, String port ) throws IOException { String url = String.format(URL_TEMPLATE, ""+ protocol,port, host, ws); String ns = NAMESPACE; BindingProvider bp; Service svc; try { QName qname = new QName(ns, ws + "Service"); Class<Service> clazz = (Class<Service>) Class.forName("com.cisco.anm." + ws + "Service"); Constructor<Service> ctor = (Constructor<Service>) clazz.getConstructor(new Class[]{URL.class, QName.class}); svc = ctor.newInstance(new Object[]{new URL(url+"?wsdl"), qname}); Method m = svc.getClass().getMethod("get"+ws+"Port", null); bp = (BindingProvider)m.invoke(svc, null); } catch (Exception e) { throw new RuntimeException(e); } return bp; }

public static void main(String args[]){ // args[0] = protocol , http or https // args[1] = IP Address or hostname of ANM server // args[2] = username, // args[3] = password. // java SampleWSClient https 10.77.241.54 admin admin if( args.length != 4 ) { System.out.println("Invalid arguments."); System.out.println("Usage: java com.cisco.anm.client.SampleWSClient <protocol(http|https)> <ANM host name> <username> <password>"); System.exit(0);

A-2API Reference Guide for Cisco Application Networking Manager 4.3

OL-24855-01


} String proto=args[0], port="", host=args[1], user=args[2], pass=args[3] ; if( proto != null && proto.equals("https")){ port = "8443"; }else if( proto.equals("http")){ port = "8080"; }else{ System.out.println("Invalid arguments."); System.out.println("Usage: java com.cisco.anm.client.SampleWSClient <protocol(http|https)> <ANM host name> <username> <password>"); System.exit(0); } OperationManager oprMgr = null; SessionToken st = null; try{ oprMgr = (OperationManager) getPort(WS_NAME, proto, port, host);

/* * Invoke login() API to get session token. */ st = oprMgr.login(user, pass); /* * Use the session token obtained from the previous call and get all ACE modules * imported in ANM. */ DeviceIDArray deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.ACE_BLADE); List<DeviceID> listDeviceId = deviceIdArr.getItem();

System.out.println("Device Type\t | Virtual Context Name\t | Module Slot\t | Chassis IP address\t | Serverfarm\t | Real Server\t | Port\t | Real IP Address\t | Weight\t | Admin State\t");

System.out.println("---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------"); for( DeviceID dev : listDeviceId ){ /* * Invoke listVirtualContext() to get all the virtual contexts for each ACE module * imported in ANM. */ DeviceIDArray vcIds = oprMgr.listVirtualContexts(st, dev); for( DeviceID vcId : vcIds.getItem() ){ /* * Invoke listServerFarms() API to get all the serverfarms configured for each VC * */ ServerfarmArray sfArr = oprMgr.listServerFarms(st, vcId); for(Serverfarm sf: sfArr.getItem() ){ /* * Invoke listServerfarmRservers() API to get all the reals configured in a serverfarm. */ SfRserverArray sfRsArr = oprMgr.listServerfarmRservers(st, vcId, sf.getName()); for( SfRserver sfRs: sfRsArr.getItem() ){ System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | " + vcId.getSlot() + "\t\t | " + vcId.getChassisIPAddr() + "\t\t | " + sfRs.getServerfarmName() + "\t | " + sfRs.getRealserverName() + "\t | "


OL-24855-01


+ sfRs.getPort() + "\t | " + sfRs.getIpAddr() + "\t | " + sfRs.getWeight() + "\t | " + sfRs.getAdminState() ); } if( sfRsArr.getItem().size() == 0) { System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | "

+ vcId.getSlot() + "\t\t | " + vcId.getChassisIPAddr() + "\t\t | "

+ sf.getName() + "\t\t " ); } } } }

System.out.println("------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------");

System.out.println("\n\n\n"); /* * Use the session token obtained from the login() API call and get all ACE modules * imported in ANM. */ deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.ACE_4710); listDeviceId = deviceIdArr.getItem();

System.out.println("Device Type\t | Virtual Context Name\t | Appliance IP address\t | Serverfarm\t | Real Server\t | Port\t | Real IP Address\t | Weight\t | Admin State\t");

System.out.println("---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------"); for( DeviceID dev : listDeviceId ){ /* * Invoke listVirtualContext() to get all the virtual contexts for each ACE module * imported in ANM. */ DeviceIDArray vcIds = oprMgr.listVirtualContexts(st, dev); for( DeviceID vcId : vcIds.getItem() ){ /* * Invoke listServerFarms() API to get all the serverfarms configured for each VC * */ ServerfarmArray sfArr = oprMgr.listServerFarms(st, vcId); for(Serverfarm sf: sfArr.getItem() ){ /* * Invoke listServerfarmRservers() API to get all the reals configured in a serverfarm. */ SfRserverArray sfRsArr = oprMgr.listServerfarmRservers(st, vcId, sf.getName()); for( SfRserver sfRs: sfRsArr.getItem() ){ System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | " + vcId.getIpAddr() + "\t\t | " + sfRs.getServerfarmName() + "\t | " + sfRs.getRealserverName() + "\t | " + sfRs.getPort() + "\t | "


OL-24855-01

Appendix A Use Case Examples Use Case 2: ActivateSuspendSfRserverClient

+ sfRs.getIpAddr() + "\t | " + sfRs.getWeight() + "\t | " + sfRs.getAdminState() ); } if( sfRsArr.getItem().size() == 0) { System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | "

+ vcId.getIpAddr() + "\t\t | " + sf.getName() + "\t\t " ); } } } }


}catch(Exception ex){ ex.printStackTrace(); }finally{ try{ /* * Close the ws session using logout() API. */ oprMgr.logout(st); }catch(Exception ex){ ex.printStackTrace(); } }

}}

Use Case 2: ActivateSuspendSfRserverClientThe following example shows a sample code to activate or suspend a real server in the server farm:

/** * Title: ActivateSuspendSfRserverClient * Description: Sample WS client code using java to activate or suspend a serverfarm real configured in ACE/CSS/CSM device * * Copyright: Copyright(C) 2010 Cisco Systems. All Rights Reserved. * Company: Cisco Systems * @version: 1.0 */

package com.cisco.anm.client;


import javax.xml.namespace.QName;


OL-24855-01


import javax.xml.ws.BindingProvider;import javax.xml.ws.Service;

import com.cisco.anm.DeviceID;import com.cisco.anm.DeviceIDArray;import com.cisco.anm.DeviceType;import com.cisco.anm.OperationManager;import com.cisco.anm.Serverfarm;import com.cisco.anm.ServerfarmArray;import com.cisco.anm.SessionToken;import com.cisco.anm.SfRserver;import com.cisco.anm.SfRserverArray;import com.cisco.anm.SuspendState;

/** * * * Sample WS client code using java to activate or suspend a serverfarm real configured in ACE/CSS/CSM device. * * Prerequiste: * To compile the file, include the stubs generated from the wsdl file. It is already packed in a jar file - dcm-ws-client-<version>.jar * * */public class ActivateSuspendSfRserverClient { static final String NAMESPACE = "http://anm.cisco.com"; static String URL_TEMPLATE = "%s://%s:%s/anm/%s"; // <protocol>://<IPAddress>:<Port>/anm/<service name> static final String WS_NAME = "OperationManager"; public static BindingProvider getPort(String ws, String protocol, String host, String port ) throws IOException { String url = String.format(URL_TEMPLATE, ""+ protocol,port, host, ws); String ns = NAMESPACE; BindingProvider bp; Service svc; try { QName qname = new QName(ns, ws + "Service"); Class<Service> clazz = (Class<Service>) Class.forName("com.cisco.anm." + ws + "Service"); Constructor<Service> ctor = (Constructor<Service>) clazz.getConstructor(new Class[]{URL.class, QName.class}); svc = ctor.newInstance(new Object[]{new URL(url+"?wsdl"), qname}); Method m = svc.getClass().getMethod("get"+ws+"Port", null); bp = (BindingProvider)m.invoke(svc, null); } catch (Exception e) { throw new RuntimeException(e); } return bp; }

public static void main(String args[]){ // args[0] = protocol , http or https // args[1] = IP Address or hostname of ANM server // args[2] = username, // args[3] = password. // args[4] = (activate|suspend)


OL-24855-01


// args[5] = sfName/rsName/rsPort/weight/rsIP // args[6] = (css|csm|vc) // args[7] = <vc name> if args[6] is VC // args[8] = <device IP Address> // args[9] = <chassis IP address> // args[10] = <slot> String usage = "For appliance vc, \n" +

"Usage: java com.cisco.anm.client.ActivateSuspendSfRserverClient (http|https) <ANM host name> <anm username> <anm password> (activate|suspend|graceful|suspend_clear_conn) <sfName/rsName/rsPort> vc <vc name> <appliance ip address>\n" +

"Example: java com.cisco.anm.client.ActivateSuspendSfRserverClient http 10.77.241.54 admin admin activate sjSF/sjRS/8080 vc Admin 10.77.241.46\n\n" +

"For module vc,\n" + "Usage: java com.cisco.anm.client.ActivateSuspendSfRserverClient

(http|https) <ANM host name> <anm username> <anm password> (activate|suspend|graceful|suspend_clear_conn) <sfName/rsName/rsPort> vc <vc name> <chassis ip address> <module slot>\n" +

"Example: java com.cisco.anm.client.ActivateSuspendSfRserverClient http 10.77.241.54 admin admin suspend sjSF/sjRS/8080 vc Admin 10.77.241.2 5\n\n" +

"For css,\n" + "Usage: java com.cisco.anm.client.ActivateSuspendSfRserverClient

(http|https) <ANM host name> <anm username> <anm password> (activate|suspend|graceful|suspend_clear_conn) <sfName/rsName/rsPort/weight> css <css ip address>\n" +

"Example: java com.cisco.anm.client.ActivateSuspendSfRserverClient https 10.77.241.54 admin admin suspend sjSF/sjRS/8080/5 css 10.77.241.100\n\n" +

"For csm,\n" + "Usage: java com.cisco.anm.client.ActivateSuspendSfRserverClient

(http|https) <ANM host name> <anm username> <anm password> (activate|suspend|graceful|suspend_clear_conn) <sfName/rsName/rsPort/rsIP> csm <chassis ip address> <module slot>\n" +

"Example: java com.cisco.anm.client.ActivateSuspendSfRserverClient https 10.77.241.54 admin admin activate sjSF/1.1.1.10/8080/1.1.1.10 csm 10.77.241.2 4\n"

;if( args.length > 10 || args.length < 8 ) {

System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0); } String proto=args[0], port="", host=args[1], user=args[2], pass=args[3] ; String activatSuspend = args[4] , sfRsName = args[5], deviceType = args[6]; if( proto != null && proto.equals("https")){ port = "8443"; }else if( proto.equals("http")){ port = "8080"; }else{ System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0); } String ipAddr="", chassisIP="", slot="", vcName="" ; DeviceID devId = new DeviceID(); if( deviceType != null && deviceType.equals("css") ){ //css devId.setDeviceType(DeviceType.CSS); devId.setIpAddr(args[7]); }else if( deviceType.equals("csm")){ // csm devId.setDeviceType(DeviceType.CSM);


OL-24855-01


devId.setChassisIPAddr(args[7]); devId.setSlot(args[8]); }else if( deviceType.equals("vc")) { if( args.length == 9 ){ //appliance devId.setDeviceType(DeviceType.VIRTUAL_CONTEXT); devId.setIpAddr(args[8]); devId.setName(args[7]); }else if (args.length == 10) { //module devId.setDeviceType(DeviceType.VIRTUAL_CONTEXT); devId.setName(args[7]); devId.setChassisIPAddr(args[8]); devId.setSlot(args[9]); }else{ System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0); } }

/* * Create SfRserver from the user's input. */ SfRserver sfRs = new SfRserver(); String[] rs = sfRsName.split("/"); if( rs.length == 3 ){ sfRs.setServerfarmName(rs[0]); sfRs.setRealserverName(rs[1]); sfRs.setPort(Integer.parseInt(rs[2])); }else if( rs.length == 4 ){ sfRs.setServerfarmName(rs[0]); sfRs.setRealserverName(rs[1]); sfRs.setPort(Integer.parseInt(rs[2])); sfRs.setWeight(Integer.parseInt(rs[3])); }else if( rs.length == 5 ){ sfRs.setServerfarmName(rs[0]); sfRs.setRealserverName(rs[1]); sfRs.setPort(Integer.parseInt(rs[2])); sfRs.setWeight(Integer.parseInt(rs[3])); sfRs.setIpAddr(rs[4]); }else{ System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0); } OperationManager oprMgr = null; SessionToken st = null; try{ oprMgr = (OperationManager) getPort(WS_NAME, proto, port, host); /* * Invoke login() API to get session token. */ st = oprMgr.login(user, pass); if(activatSuspend.equals("activate")){ System.out.println("Start: Activate realserver"); /* * Invoke the activate api to activate the rserver in the given deviceId. */ oprMgr.activateServerfarmRserver(st, devId, sfRs, "Activate Rserver from Java WS Client.");


OL-24855-01


System.out.println("Completed: Activate realserver"); }else if(activatSuspend.equals("suspend")){ System.out.println("Start: Suspend realserver"); /* * Invoke the activate api to activate the rserver in the given deviceId. */ oprMgr.suspendServerfarmRserver(st, devId, sfRs, SuspendState.SUSPEND, "Suspend Rserver from JAVA WS Client."); System.out.println("Completed: Suspend realserver"); }else if (activatSuspend.equals("graceful")){ System.out.println("Start: Graceful suspend realserver"); /* * Invoke the activate api to activate the rserver in the given deviceId. */ oprMgr.suspendServerfarmRserver(st, devId, sfRs, SuspendState.GRACEFUL, "Graceful Suspend Rserver from JAVA WS Client."); System.out.println("Completed: Graceful suspend realserver"); }else if (activatSuspend.equals("suspend_clear_conn")){ System.out.println("Start: Suspend with clear connection realserver"); /* * Invoke the activate api to activate the rserver in the given deviceId. */ oprMgr.suspendServerfarmRserver(st, devId, sfRs, SuspendState.SUSPEND_CLEAR_CONNECTIONS, "Suspend with Clear Connection Rserver from JAVA WS Client."); System.out.println("Completed: Suspend with clear connection realserver"); }else{ System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0); } }catch(Exception ex){ ex.printStackTrace(); }finally{ try{ /* * Close the ws session using logout() API. */ oprMgr.logout(st); }catch(Exception ex){ ex.printStackTrace(); } }

}}

Note As a prerequisite to compile the sample client code, you should have the client java file generated from the ANM WSDL files in the classpath. The ANM_web_services_API_client.jar file is located at the following location: http://developer.cisco.com/web/anm/docs.


OL-24855-01

Appendix A Use Case Examples Use Case 3: Virtual Server WS Client

Use Case 3: Virtual Server WS ClientThe following example shows a sample code that works with the ANM APIs that are related to virtual servers and allow you to activate, suspend, and list the virtual servers:

/** * Title: Virtual Server WS Client code * Description: Sample WS client code using java to work with Virtual server related APIs in ANM * * Copyright: Copyright(C) 2011 Cisco Systems. All Rights Reserved. * Company: Cisco Systems * @version: 1.0 */




import com.cisco.anm.DeviceID;import com.cisco.anm.DeviceIDArray;import com.cisco.anm.DeviceType;import com.cisco.anm.OperationManager;import com.cisco.anm.Serverfarm;import com.cisco.anm.ServerfarmArray;import com.cisco.anm.SessionToken;import com.cisco.anm.SfRserver;import com.cisco.anm.SfRserverArray;import com.cisco.anm.SuspendState;import com.cisco.anm.Vserver;import com.cisco.anm.VserverArray;

/** * * * Sample WS client code using java to work with Virtual server related APIs in ANM * * Prerequiste: * To compile the file, include the stubs generated from the wsdl file. It is already packed in a jar file - dcm-ws-client-<version>.jar * * */public class VserverWSClient { static final String NAMESPACE = "http://anm.cisco.com"; static String URL_TEMPLATE = "%s://%s:%s/anm/%s"; // <protocol>://<IPAddress>:<Port>/anm/<service name> static final String WS_NAME = "OperationManager"; public static BindingProvider getPort(String ws, String protocol, String host, String port ) throws IOException { String url = String.format(URL_TEMPLATE, ""+ protocol,port, host, ws); String ns = NAMESPACE;


OL-24855-01


BindingProvider bp; Service svc; try { QName qname = new QName(ns, ws + "Service"); Class<Service> clazz = (Class<Service>) Class.forName("com.cisco.anm." + ws + "Service"); Constructor<Service> ctor = (Constructor<Service>) clazz.getConstructor(new Class[]{URL.class, QName.class}); svc = ctor.newInstance(new Object[]{new URL(url+"?wsdl"), qname}); Method m = svc.getClass().getMethod("get"+ws+"Port", null); bp = (BindingProvider)m.invoke(svc, null); } catch (Exception e) { throw new RuntimeException(e); } return bp; }

public static void main(String args[]){ // args[0] = protocol , http or https // args[1] = IP Address or hostname of ANM server // args[2] = username, // args[3] = password. // args[4] = (activate|suspend|listAllVirtualServer) // args[5] = virtualServerName/(policymap) // args[6] = (css|csm|vc) // args[7] = <vc name> if args[6] is VC // args[8] = <device IP Address> // args[9] = <chassis IP address> // args[10] = <slot> String usage = "For ACE4710 Appliance Virtual Context, \n" +

"Usage: java com.cisco.anm.client.VserverWSClient (http|https) <ANM host name> <anm username> <anm password> (activate|suspend) <(virtualServerName/policymap) | virtualServerName> vc <vc name> <appliance ip address>\n" +

"Example: java com.cisco.anm.client.VserverWSClient http 10.77.241.54 admin admin activate sjVS/global vc Admin 10.77.241.46\n\n" +

"For ACE Module Virtual Context,\n" + "Usage: java com.cisco.anm.client.VserverWSClient (http|https) <ANM

host name> <anm username> <anm password> (activate|suspend) <(virtualServerName/policymap) | virtualServerName> vc <vc name> <chassis ip address> <module slot>\n" +

"Example: java com.cisco.anm.client.VserverWSClient http 10.77.241.54 admin admin suspend sjVS/global vc Admin 10.77.241.2 5\n\n" +

"For CSS,\n" + "Usage: java com.cisco.anm.client.VserverWSClient (http|https) <ANM

host name> <anm username> <anm password> (activate|suspend) <(virtualServerName/policymap) | virtualServerName> css <css ip address>\n" +

"Example: java com.cisco.anm.client.VserverWSClient https 10.77.241.54 admin admin suspend sjVS/global css 10.77.241.100\n\n" +

"For CSM,\n" + "Usage: java com.cisco.anm.client.VserverWSClient (http|https) <ANM

host name> <anm username> <anm password> (activate|suspend) <(virtualServerName/policymap) | virtualServerName> csm <chassis ip address> <module slot>\n" +

"Example: java com.cisco.anm.client.VserverWSClient https 10.77.241.54 admin admin activate sjVS/global csm 10.77.241.2 4\n\n" +

"To list all Virtualservers in ANM ,\n" + "Usage: java com.cisco.anm.client.VserverWSClient (http|https) <ANM

host name> <anm username> <anm password> listAllVirtualServer\n" +


OL-24855-01


"Example: java com.cisco.anm.client.VserverWSClient https 10.77.241.54 admin admin listAllVirtualServer\n\n";

if( args.length > 10 || args.length < 8 ) {if( args.length != 5 ) {

System.out.println("Invalid arguments."); System.out.println(usage); System.exit(0);

} }

if( args.length != 5 ) {String proto=args[0], port="", host=args[1], user=args[2], pass=args[3] ;String activatSuspend = args[4] , vsName = args[5], deviceType = args[6];

if( proto != null && proto.equals("https")){port = "8443";

}else if( proto.equals("http")){port = "8080";

}else{System.out.println("Invalid arguments.");System.out.println(usage);System.exit(0);

}DeviceID devId = new DeviceID();if( deviceType != null && deviceType.equals("css") ){ //css

devId.setDeviceType(DeviceType.CSS);devId.setIpAddr(args[7]);

}else if( deviceType.equals("csm")){ // csmdevId.setDeviceType(DeviceType.CSM);devId.setChassisIPAddr(args[7]);devId.setSlot(args[8]);

}else if( deviceType.equals("vc")) {if( args.length == 9 ){

//appliancedevId.setDeviceType(DeviceType.VIRTUAL_CONTEXT);devId.setIpAddr(args[8]);devId.setName(args[7]);

}else if (args.length == 10) {//moduledevId.setDeviceType(DeviceType.VIRTUAL_CONTEXT);devId.setName(args[7]);devId.setChassisIPAddr(args[8]);devId.setSlot(args[9]);


}}

/* * Create Vserver from the user's input. */Vserver virtualServer = new Vserver();String[] vs = vsName.split("/");if( vs.length == 1 ){

virtualServer.setVirtualserverName(vs[0]);}else if( vs.length == 2 ){

virtualServer.setVirtualserverName(vs[0]);virtualServer.setPolicyMapName(vs[1]);

}else{System.out.println("Invalid arguments.");System.out.println(usage);


OL-24855-01


System.exit(0);}OperationManager oprMgr = null;SessionToken st = null;try{

oprMgr = (OperationManager) getPort(WS_NAME, proto, port, host);

/* * Invoke login() API to get session token. */st = oprMgr.login(user, pass);

if(activatSuspend.equals("activate")){System.out.println("Start: Activate Virtualserver");/* * Invoke the activate api to activate the vserver in the given

deviceId. */oprMgr.activateVirtualServer(st, devId, virtualServer, "Activate

Vserver from Java WS Client.");System.out.println("Completed: Activate Virtualserver");

}else if(activatSuspend.equals("suspend")){

System.out.println("Start: Suspend Virtualserver");/* * Invoke the suspend api to suspend the vserver in the given deviceId. */oprMgr.suspendVirtualServer(st, devId, virtualServer, "Suspend Vserver

from JAVA WS Client.");System.out.println("Completed: Suspend Virtualserver");

}

else{System.out.println("Invalid arguments.");System.out.println(usage);System.exit(0);

}oprMgr.listVirtualServers(st, devId, true);

}catch(Exception ex){ex.printStackTrace();

}finally{try{

/* * Close the ws session using logout() API. */oprMgr.logout(st);


}}

}else if(args.length == 5){

String proto=args[0], port="", host=args[1], user=args[2], pass=args[3];OperationManager oprMgr = null;SessionToken st = null;if( proto != null && proto.equals("https")){

port = "8443";}else if( proto.equals("http")){

port = "8080";}else{

System.out.println("Invalid arguments.");System.out.println(usage);System.exit(0);


OL-24855-01


}try{



DeviceID devId = new DeviceID();DeviceIDArray deviceIdArr = oprMgr.listDeviceIds(st,

DeviceType.ACE_BLADE);List<DeviceID> listDeviceId = deviceIdArr.getItem();System.out.println("ACE Module");System.out.println("Device Type\t | Virtual Context Name\t | Module Slot\t

| Chassis IP address\t | Virtualserver Name\t");

System.out.println("---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------");

for( DeviceID dev : listDeviceId ){ /* * Invoke listVirtualContext() to get all the virtual contexts for each ACE

module * imported in ANM. */ DeviceIDArray vcIds = oprMgr.listVirtualContexts(st,dev);

for( DeviceID vcId : vcIds.getItem() ){/*

* Invoke listVirtualservers() API to get all the Virtual Servers (recognized by ANM) configured for each VC

* */

VserverArray vsArr = oprMgr.listVirtualServers(st, vcId, false);for(Vserver vs: vsArr.getItem() ){

System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | "

+ vcId.getSlot() + "\t\t | " + vcId.getChassisIPAddr() + "\t\t | "

+ vs.getVirtualserverName());}

}}


System.out.println("\n\n\n"); /* * Use the session token obtained from the login() API call and get all

ACE4710 Appliances * imported in ANM. */

deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.ACE_4710);listDeviceId = deviceIdArr.getItem();System.out.println("ACE4710 Appliance");System.out.println("Device Type\t | Virtual Context Name\t | Appliance IP

address\t | Virtualserver Name\t ");



OL-24855-01


for( DeviceID dev : listDeviceId ){/*

* Invoke listVirtualContext() to get all the virtual contexts for each ACE module

* imported in ANM. */

DeviceIDArray vcIds = oprMgr.listVirtualContexts(st,dev);for( DeviceID vcId : vcIds.getItem() ){

/* * Invoke listVirtualServers() API to get all the Virtual Servers

(recognized by ANM) configured for each VC * */

VserverArray vsArr = oprMgr.listVirtualServers(st, vcId, false);for(Vserver vs: vsArr.getItem() ){

System.out.println(vcId.getDeviceType() + "\t | " + vcId.getName() + "\t\t | "

+ vcId.getIpAddr() + "\t\t | " + vs.getVirtualserverName() + "\t | "

);}

}}


System.out.println("\n\n\n"); /* * Use the session token obtained from the login() API call and get all CSM

modules * imported in ANM. */

deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.CSM);listDeviceId = deviceIdArr.getItem();System.out.println("CSM");System.out.println("Device Type\t | Module Slot\t | Chassis IP address\t |

Virtualserver Name\t ");



* Invoke listVirtualServers() API to get all the Virtual Servers(recognized by ANM) configured for each CSM * */

VserverArray vsArr = oprMgr.listVirtualServers(st, dev, false);for(Vserver vs: vsArr.getItem() ){

System.out.println(dev.getDeviceType() + "\t | " + dev.getSlot() + "\t\t | " + dev.getChassisIPAddr() + "\t\t | "

+ vs.getVirtualserverName() + "\t | " );

}

}


System.out.println("\n\n\n");


OL-24855-01


/* * Use the session token obtained from the login() API call and get all CSS

devices. * imported in ANM. */

deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.CSS);listDeviceId = deviceIdArr.getItem();System.out.println("CSS");System.out.println("Device Type\t | Device IP address\t | Virtualserver

Name\t ");



* Invoke listVirtualServers() API to get all the Virtual Servers configured for each CSS device. * */

VserverArray vsArr = oprMgr.listVirtualServers(st, dev, false);for(Vserver vs: vsArr.getItem() ){

System.out.println(dev.getDeviceType() + "\t | " + dev.getIpAddr() + "\t\t | " +

vs.getVirtualserverName() + "\t | " );

}

}


System.out.println("\n\n\n"); }

catch(Exception ex){ex.printStackTrace();

}finally{try{

/* * Close the ws session using logout() API. */oprMgr.logout(st);


}}

}else {


} }}


OL-24855-01

Appendix A Use Case Examples Use Case 4: GSSWSClient

Use Case 4: GSSWSClientThe following example shows a sample code to activate, suspend, and list the answers and DNS rules configured on a GSS:

/** * Title: GSSWSClient * Description: Sample WS client code using java to activate/suspend/list the answer/dnsrule configured in GSS device * * Copyright: Copyright(C) 2011 Cisco Systems. All Rights Reserved. * Company: Cisco Systems * @version: 1.0 */




import com.cisco.anm.AnswerArray;import com.cisco.anm.DeviceID;import com.cisco.anm.DeviceIDArray;import com.cisco.anm.DeviceType;import com.cisco.anm.DnsRuleArray;import com.cisco.anm.OperationManager;import com.cisco.anm.Serverfarm;import com.cisco.anm.ServerfarmArray;import com.cisco.anm.SessionToken;import com.cisco.anm.SfRserver;import com.cisco.anm.Answer;import com.cisco.anm.DnsRule;import com.cisco.anm.SfRserverArray;import com.cisco.anm.SuspendState;

/** * * * Sample WS client code using java to activate/suspend/list the answer/dnsrule configured in GSS device * * Prerequiste: * To compile the file, include the stubs generated from the wsdl file. It is already packed in a jar file - dcm-ws-client-<version>.jar * * */public class GSSWSClient {

static final String NAMESPACE = "http://anm.cisco.com"; static String URL_TEMPLATE = "%s://%s:%s/anm/%s"; //

<protocol>://<IPAddress>:<Port>/anm/<service name>static final String WS_NAME = "OperationManager";

public static BindingProvider getPort(String ws, String protocol, String host, String port ) throws IOException {


OL-24855-01


String url = String.format(URL_TEMPLATE, ""+ protocol,port, host, ws);String ns = NAMESPACE;

BindingProvider bp;

Service svc;try {

QName qname = new QName(ns, ws + "Service");Class<Service> clazz = (Class<Service>) Class.forName("com.cisco.anm." + ws +

"Service");Constructor<Service> ctor = (Constructor<Service>) clazz.getConstructor(new

Class[]{URL.class, QName.class});svc = ctor.newInstance(new Object[]{new URL(url+"?wsdl"), qname});Method m = svc.getClass().getMethod("get"+ws+"Port", null);bp = (BindingProvider)m.invoke(svc, null);

} catch (Exception e) {throw new RuntimeException(e);

}return bp;

}

public static void main(String args[]){

// args[0] = protocol , http or https// args[1] = IP Address or hostname of ANM server// args[2] = username,// args[3] = password.// args[4] = (activate|suspend|list)// args[5] = (answer|dns)// args[6] = <device IP Address>// args[7] = <answerName/ansIpAdress> | <ruleName/sourceAddress>

String usage = "For Answer activate/suspend operation , \n" + "Usage: java com.cisco.anm.client.GSSWSClient (http|https) <ANM host name> <anm

username> <anm password> (activate|suspend) (answer) <GSS ip address> <answerName/ansIpAdress> \n" +

"Example: java com.cisco.anm.client.GSSWSClient http 10.77.241.54 admin admin activate answer 10.77.241.46 VIP-CSCO-9-99/11.0.9.99 \n\n" +

"To list all Answers, \n" + "Usage: java com.cisco.anm.client.GSSWSClient (http|https) <ANM host name> <anm

username> <anm password> (list) (answer) \n" +"Example: java com.cisco.anm.client.GSSWSClient http 10.77.241.54 admin admin list

answer \n\n" +

"For DNS rule activate/suspend operation , \n" + "Usage: java com.cisco.anm.client.GSSWSClient (http|https) <ANM host name> <anm

username> <anm password> (activate|suspend) (dns) <GSS ip address> <ruleName> \n" +"Example: java com.cisco.anm.client.GSSWSClient http 10.77.241.54 admin admin

activate dns 10.77.241.46 RULE-CSCO-9-96 \n\n" +

"To list all DNS rules, \n" + "Usage: java com.cisco.anm.client.GSSWSClient (http|https) <ANM host name> <anm

username> <anm password> (list) <dns> <GSS name> \n" +"Example: java com.cisco.anm.client.GSSWSClient http 10.77.241.54 admin admin list

dns \n\n";if(args.length < 8 ) {

if( args.length != 6 ){System.out.println("Invalid arguments.");System.out.println(usage);System.exit(0);

}


OL-24855-01


}

String proto=args[0], port="", host=args[1], user=args[2], pass=args[3] ;String opeartion = args[4] , type = args[5];

if( proto != null && proto.equals("https")){port = "8443";

}else if( proto.equals("http")){port = "8080";


}

OperationManager oprMgr = null;SessionToken st = null;String operData = null;String[] data = null;DeviceID GSS = null;if(args.length==8){

GSS = new DeviceID();GSS.setDeviceType(DeviceType.GSS);GSS.setSlot("0");GSS.setIpAddr(args[6]);operData = args[7];data = operData.split("/");

}

if(type.equalsIgnoreCase("Answer")){

Answer answer = new Answer();if(!opeartion.equalsIgnoreCase("list")){

if( data.length == 2 ){answer.setAnswerName(data[0]);answer.setIpAddr(data[1]);answer.setType("vip");

}else{


}}try{



if(opeartion.equalsIgnoreCase("activate")){System.out.println("Start: Activate Answer");/* * Invoke the activate api to activate the answer in the given

deviceId. */oprMgr.activateAnswer(st, GSS, answer, "Activate Answer from Java WS

Client.");

System.out.println("Completed: Activate answer");}else if(opeartion.equalsIgnoreCase("suspend")){


OL-24855-01


System.out.println("Start: Suspend answer");/* * Invoke the activate api to suspend the answer in the given deviceId. */oprMgr.suspendAnswer(st, GSS, answer, "Suspend Answer from Java WS

Client.");

System.out.println("Completed: Suspend answer");}else if (opeartion.equalsIgnoreCase("list")){

System.out.println("Start: List Answers");DeviceIDArray deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.GSS);List listDeviceId = deviceIdArr.getItem();for( DeviceID gss: deviceIdArr.getItem() ){

/* * Invoke the list api to get the list of answers in the given

deviceId. */AnswerArray answerArray = oprMgr.listAnswers(st, gss);int list_size = 0;if (answerArray.getItem()!= null &&

!answerArray.getItem().isEmpty())list_size = answerArray.getItem().size();

System.out.println("GSS Name\t | Answer Name\t | Answer IP Address\t | Config State \t | PGSSM Oper State \t | Answer Group \t | Location \t");


for( Answer ans: answerArray.getItem() ){ System.out.println(gss.getName() + "\t | " +

ans.getAnswerName() + "\t | " + ans.getIpAddr() + "\t\t | " + ans.getConfigState() + "\t\t | " + ans.getOperState()

+ "\t\t | " + ans.getAnswerGroups() + "\t\t | "+ ans.getLocation() + "\t\t ");

}if( answerArray.getItem().size() == 0) {

System.out.println("No answers is configured in the given GSS device" );

}


}if( deviceIdArr.getItem().size() == 0) {

System.out.println("No GSS device is imported in this ANM server" );

}


System.out.println("Completed: List Answers");}

} catch(Exception ex){

ex.printStackTrace();}finally{

try{/* * Close the ws session using logout() API.


OL-24855-01


*/oprMgr.logout(st);


}}

}else if(type.equalsIgnoreCase("dns")){

DnsRule dnsRule = new DnsRule();if(!opeartion.equalsIgnoreCase("list")){

if( data.length == 1 ){dnsRule.setDnsRuleName(data[0]);//dnsRule.setSourceAddress(data[1]);


}}try{



if(opeartion.equalsIgnoreCase("activate")){System.out.println("Start: Activate dns rule");/* * Invoke the activate api to activate the dns rule in the given

deviceId. */oprMgr.activateDnsRule(st, GSS, dnsRule, "Activate DNS rule from Java

WS Client.");

System.out.println("Completed: Activate dns rule");}else if(opeartion.equalsIgnoreCase("suspend")){

System.out.println("Start: Suspend dns rule");/* * Invoke the activate api to suspend the dns rule in the given

deviceId. */oprMgr.suspendDnsRule(st, GSS, dnsRule, "Suspend DNS rule from Java WS

Client.");

System.out.println("Completed: Suspend dns rule");}else if (opeartion.equalsIgnoreCase("list")){

DeviceIDArray deviceIdArr = oprMgr.listDeviceIds(st, DeviceType.GSS);List listDeviceId = deviceIdArr.getItem();System.out.println("Start: List DNS rules");for( DeviceID gss: deviceIdArr.getItem() ){

/* * Invoke the list api to get the list of dns rule from the given

deviceId. */DnsRuleArray dnsruleArray = oprMgr.listDnsRules(st, gss);int list_size = 0;if (dnsruleArray.getItem()!= null &&

!dnsruleArray.getItem().isEmpty())System.out.println("GSS name\t | DNS name\t | Source Address \t

| Domains \t | Config state \t | Answer Group \t | Owner \t");


OL-24855-01



for( DnsRule dns: dnsruleArray.getItem() ){ System.out.println(gss.getName() + "\t | " +

dns.getDnsRuleName() + "\t | " + dns.getSourceAddress() + "\t\t | " + dns.getDomains() + "\t\t | " + dns.getDnsConfigState()

+ "\t\t | "+ dns.getAnswerGroups() + "\t\t | " + dns.getOwner() +

"\t\t ");}if( dnsruleArray.getItem().size() == 0) {

System.out.println("No dns rule is configured in the given GSS device" );

}


}if( deviceIdArr.getItem().size() == 0) {

System.out.println("No GSS device is imported in this ANM server" );

}


System.out.println("Completed: List DNS rule");}

}catch(Exception ex){

ex.printStackTrace();}finally{

try{/* * Close the ws session using logout() API. */oprMgr.logout(st);


}}

}else{


}

}}


OL-24855-01


I N D E X

A

activateAnswer (GSS) 2-42

activateServerfarmRserver 2-33

activateVirtualServer 2-23

addRserverToServerfarm 2-27

C

changeServerfarmRserverWeight 2-39

Custom Application Errors 4-1

D

Device Configuration service 2-1

DeviceID 3-2

G

getVMMappingInfo 2-50

L

listAnswers (GSS) 2-19

listDeviceIDs 2-5

listDNSRules (GSS) 2-21

listRservers 2-14

listServerfarmRservers 2-16

listServerfarms 2-12

listVirtualContexts 2-7

listVirtualServers 2-9

Login 2-3

Logout 2-4

R

removeRserverFromServerfarm 2-30

Rserver 3-3

S

Serverfarm 3-3

SfRserver 3-4

SOAP Message Traffic 4-1

SOAP Message Traffic and Time Taken to Invoke an API 4-1

suspendAnswer (GSS) 2-44

suspendServerfarmRserver 2-36

suspendVirtualServer 2-25

V

VMMappingInfo 3-4

W

Web Services Description Language 1-2

IN-1uide for Cisco Application Networking Manager 4.3

Index

IN-2API Reference Guide for Cisco Application Networking Manager 4
.3
OL-24855-01

web service api reference guide for cisco application ... · iii api reference guide for cisco...

Documents