Cisco MDS 9000 Family Fabric Manager Configuration Guide
Fabric Manager Web Services
Downloads: This chapterpdf (PDF - 157.0KB) The complete bookPDF (PDF - 48.18MB) | Feedback

Fabric Manager Web Services

Table Of Contents

Fabric Manager Web Services

About Fabric Manager Web Services

Web Services Specifications

XML

SOAP

HTTP/HTTPS

WDSL

Logon Service

requestToken

validateToken

Authentication or Token

IdentityManager

San Service

Service Endpoint Interface (SEI)

Methods

getFabrics

getFabricByIP

getFabricByKey

getFabricBySwitchKey

getSwitchesByFabric

getSwitch

getSwitchByKey

getSwitchIPByName

getSwitchIPByKey

getNeighborSwitches

getVsans

getVsan

getIsls

discoverFabric

manageFabric

unManageFabric

closeFabric

purgeFabric

getEndports

getEnclosures

getEndPortByFWwn

getEndPortByKey

getEndPortAttachedToSw

getEnclosureByName

getEnclosureByKey

getEnclosureByPWwn

updateEnclosure

updateEndportEnclosure

getHosts

getHost

getHostByFabric

getStorages

getStorageByFabric

getHostPorts

Error Codes


Fabric Manager Web Services


This chapter describes the Fabric Manager Web Services (FMWS) application program interface (API). This chapter includes the following sections:

About Fabric Manager Web Services

Web Services Specifications

Logon Service

San Service

Service Endpoint Interface (SEI)

Methods

Error Codes

About Fabric Manager Web Services

The Cisco Fabric Manager Web Services (FMWS) enables third-party vendors to access Fabric Manager core software functionalities as remote procedure calls. Web Services extend the World Wide Web infrastructure to provide a method to softwares connecting to other software applications. Applications access Web Services using many protocols and data formats such as HTTP, HTTPS, XML, and SOAP. Web Services combine the best aspects of component-based development and the web. Web Services makes Fabric Manager an enterprise class application allowing it to be interoperable with other software platforms.

This chapter defines the APIs exposed by the Fabric Manager Web Services feature.

Web Services Specifications

Web Services specifications compose together to provide interoperable protocols for security, communication and syntax for representing data.

XML

XML is the data format that defines the structure of the message. XML Web Services architecture allows programs written in different languages on different platforms to communicate with each other in a standards-based way. XML Web Services expose useful functionality to Web users through a standard Web protocol (SOAP).

SOAP

Simple Object Access Protocol (SOAP) is the communications protocol for Web Services. SOAP is a specification that defines the XML format for messages. The advantage of SOAP is that it has been implemented on many different hardware and software platforms.

HTTP/HTTPS

HTTP/HTTPS is the transport layer of the service. HTTP/HTTPS allows data to traverse the network easily and is widely accepted. It is also considered as platform neutral. Every Fabric Manager Web Services operation is through HTTP/HTTPS.

WDSL

A WSDL definition is an XML document with a root definition element from the http://schemas.xmlsoap.org/wsdl/ namespace. Fabric Manager Web Services uses the WSDL document to publish which operations of Fabric Manager are available. The definitions element may contain several other elements including types, message, portType, binding, and service, all of which come from the namespace. WSDL is published on FMServer at http://localhost/LogonWSService/LogonWS?wsdl

Logon Service

LogonWS makes IdentityManager's operations available as Web Service calls. LogonWS allows the following operations:

requestToken

This method returns a token string that must be passed in as the header of the SOAP message. Once the username and password is authentication using Fabric Manager's SecurityManager, the token is generated and is kept valid for the number of milliseconds specified in the expiration argument.

Parameters

username—Name of the user.

password—Password of the user.

expiration—Time (in milliseconds).

Return Value

Session token.

Error

Error code: 201—Invalid argument in Web Service exception.

validateToken

This method returns true or false depending on the validity of the token. If the token has expired, it returns false, or else it returns true.

Parameters

token—Session Token.

Return Value

Boolean value "True" if the Fabric Manager accepts the token.

Error

Error code: 201—Invalid argument in Web Service exception.

Authentication or Token

To interact with Fabric Manager Web Services, the user must obtain a token through LogonWS and attach this token to the header message of every SOAP requests. Fabric Manager Web Services verifies user credentials using a unique token string that is administered by LogonWS. At any given time, HTTPS should be deployed to secure the communication channel. The following example displays the format of the header message:

<?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:Header 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" >
   <m:Token xmlns:m="http://www.w3schools.com/transaction/">
     token string is put here
   </m:Token></SOAP-ENV:Header>
 <SOAP-ENV:Body>
  <getFabrics xmlns="http://ep.jaxws.dcbu.cisco.com/"/>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

IdentityManager

IdentityManager provide identity services and manage the user credentials that are required by Web Services. It is the token provider who administers and maintains tokens. It authenticates the user, generates tokens, and validates or expires tokens by periodically checking and clearing the cache.

San Service

San Service is an Enterprise Java Beans (EJB) component that manages SAN-related service requests and executes queries on Fabric Manager for information. SanWS checks with IdentityManager for authentication before performing the request. A valid token string tells San Service that the user is a Fabric Manager user and it must honor and execute the request. After retrieving the required information it sends the result back to the user. SanWS logs errors in fms_ws.log.

Service Endpoint Interface (SEI)

Service endpoint interface (SEI) of SanWS defines the operations of the service. These methods are published to the end users.

Methods

getFabrics

Returns the list of all open fabrics.

Return Value

An array of open fabrics.

Error

Error Code: 300— General SAN Service exception.

getFabricByIP

Returns the list of fabrics associated with the IP address of a given switch.

Parameters

ipAddress—IP address of the switch.

Return Value

List of all fabrics associated with the specificIP address.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getFabricByKey

Returns the list of fabrics associated with the specified key.

Parameters

key—Key of the fabric.

Return Value

List of all fabrics associated with the specified key.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getFabricBySwitchKey

Returns the list of fabrics associated with the specified seed switch key (WWN).

Parameters

swkey—Seed switch key of the fabric.

Return Value

List of all fabrics associated with the specified seed switch key.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getSwitchesByFabric

Returns the list of switches associated with the specified fabric key.

Parameters

key—Key of the fabric.

Return Value

List of all fabrics associated with the specified fabric key.

Error

Error Code: 300— General SAN Service exception.

getSwitch

Returns the list of switches on all the fabrics.

Parameters

key—Key of the fabric.

Return Value

List of all fabrics associated with the specified fabric key.

Error

Error Code: 300— General SAN Service exception.

getSwitchByKey

Returns the switch associated with the specified switch key object.

Parameters

key—Key of the fabric.

Return Value

Switch associated with the specified switch key.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getSwitchIPByName

Returns the IP address associated with the specified system name or switch name.

Parameters

sysname—Name of the system or switch.

Return Value

IP address associated with the specified system name.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getSwitchIPByKey

Returns the IP address of the switch associated with the specified WwnKey object.

Parameters

key—WWN Key object.

Return Value

IP address associated with the specifiedWwnKey object.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getNeighborSwitches

Returns the list of neighboring switches associated with the specified WwnKey.

Parameters

key—Wwn Key object.

Return Value

List of neighboring switches associated with the specifiedWwnKey.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

Error code: 302—SAN does not found objects by query key exception.

getVsans

Returns the list of VSANs in the fabric associated with the specified fabric key.

Parameters

key—fabric key object.

Return Value

List of VSANs in the fabric associated with the specified fabric key.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getVsan

Returns the VSAN in the fabric associated with the specified VSAN key object.

Parameters

key—VSAN key object.

Return Value

VSANs in the fabric associated with the specified VSAN key object.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getIsls

Returns the list of ISLs in the VSAN associated with the specified VSAN key.

Parameters

key—VSAN key.

Return Value

Array of ISL objects in the VSAN associated with the specified VSAN key.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

discoverFabric

This API will open the fabric. This function requires the IP address of the seed switch and SNMP credentials.

Parameters

seed—IP address of the seed switch.

user—SNMP Credential.

Return Value

Boolean value is True, if the discovery was successful.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

Error Code: 100— Authentication failure exception.

Error code: 101—Invalid credentials exception.

manageFabric

Returns true or false depending managability of the fabric.

Parameters

key—Fabric key.

Return Value

Returns true if the fabric can be identified ot managed. Returns false if the fabric cannot be identified ot managed.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

unManageFabric

This function is used to unmanage a fabric.

Parameters

key—Fabric key.

Return Value

None.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

closeFabric

This functions is used to un manage and close a fabric.

Parameters

key—Fabric key.

Return Value

None.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

purgeFabric

This functions is used to purge the specified fabric data both from Fabric Manager cache and database.

Parameters

key—Fabric key.

Return Value

None.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

Error code: 302—SAN does not found objects by query key exception.

getEndports

Returns the list of all the end ports known to the Fabric Manager.

Return Value

An array of all the end ports.

Error

Error Code: 300— General SAN Service exception.

getEnclosures

Returns the list of all the enclosures known to the Fabric Manager.

Return Value

An array of enclosure objects.

Error

Error Code: 300— General SAN Service exception.

getEndPortByFWwn

Returns the end port based on FPort WWN.

Parameters

wwn—WWN of the FPort.

Return Value

Returns an array of end port based on FPort WWN. Returns null if there are no end ports associated with the FPort.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getEndPortByKey

Returns the end port based on Switch WWN.

Parameters

key—WWN of the node.

Return Value

Returns the end port based on Switch WWN. Returns null if there are no end ports associated with the Switch.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getEndPortAttachedToSw

Returns the end ports that are associated with a switch.

Parameters

key—IP address of the switch.

Return Value

Returns the end ports based on switch.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getEnclosureByName

Returns the enclosure based on the name.

Parameters

name—Name of the enclosure object.

Return Value

Returns the enclosure object..

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getEnclosureByKey

Returns the enclosure based on the name.

Parameters

name—Name of the enclosure object.

Return Value

Returns the enclosure object.

Error

Error Code: 300— General SAN Service exception .

Error code: 201—Invalid argument in Web Service exception.

getEnclosureByPWwn

Returns the enclosure that are associated with a physical WWN.

Parameters

wwn—Physical WWN of the switch.

Return Value

Returns the enclosure based on physical WWN.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

updateEnclosure

Update the enclosure with the value that is passed as parameter.

Parameters

value—Value to update the enclosure.

Return Value

None.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

updateEndportEnclosure

Update the end port enclosure with the value that is passed as parameter.

Parameters

endportKey—Value for the endportKey.

enclosureKey—Value for the enclosureKey.

Return Value

None.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getHosts

Returns the list of all the host enclosures known to Fabric Manager.

Return Value

Returns the list of all the host enclosures known to Fabric Manager.

Error

Error Code: 300— General SAN Service exception.

getHost

Returns the name of hosts in a VSAN.

Parameters

key—Name of the VSAN.

Return Value

Returns the name of the hosts in tthe specified VSAN.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getHostByFabric

Returns the name of hosts in a fabric.

ValidationException is thrown if any of the following situation occurs:

If the argument passed is null.

If the argument does not contain a valid key.

Parameters

key—Name of the fabric.

Return Value

Returns the name of the hosts in the specified VSAN.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getStorages

Returns the list of all the storage device enclosures known to Fabric Manager.

Return Value

An array of all the storage device enclosures known to Fabric Manager.

Error

Error Code: 300— General SAN Service exception.

getStorageByFabric

Returns the name of storage device enclosures in a fabric.

Parameters

key—Name of the fabric.

Return Value

Returns the name of the storages in the specified fabric.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

getHostPorts

Returns the list of all the host end ports in a fabric.

Parameters

key—Name of the fabric.

Return Value

An array of all the host ports in a fabric.

Error

Error Code: 300— General SAN Service exception.

Error code: 201—Invalid argument in Web Service exception.

Error Codes

Error Code
Description

100

Authentication failure.

101

Invalid credential.

102

Invalid privilage.

103

Invalid token.

200

Web Service error.

201

Invalid argument in Web Service function.

202

Unreachable Web Service server.

300

SAN service error.

301

Invalid query key in SAN service