• No results found

RingMaster Software Version 7.6 Web Services API User Guide

N/A
N/A
Info
Download
Protected

Academic year: 2021

Share "RingMaster Software Version 7.6 Web Services API User Guide"

Copied!
22
0
0

Loading.... (view fulltext now)

Download now ( 22 Page )

Full text

(1)

Release

7.6

31 October 2011 (Release Date)

(2)

Contents

Overview

The RingMaster 7.6 Web Services API is an XML-based API used to set up the SNMP interface and provide other alarm / inventory details using polling rather than using a trap mechanism.

 RingMaster Agent provides the RingMaster 7.6 Web Services API so that upstream applications can retrieve the version of RingMaster. The version will correspond to the REST interface version, which is not the same as the RingMaster software version

 RingMaster Agent allows the RingMaster 7.6 Web Services API to retrieve an alarm summary from the RingMaster alarm module (each alarm type, criticality and counts).. The alarm summary can be filtered based on query criteria using the Web API. (For example, client failure alarms with a certain SSID).

 The Web API provides inventory information, such as a list of devices (MXs and APs) and corresponding information in RingMaster (name, model, serial number, build number, system IP, location, contact info, admin state, and operational status).

Overview . . . 2

API Interface . . . 3

Licensing . . . 4

Web Services . . . 4

Client Summary . . . 9

AirDefense Server LA-200 Managed MXs SNMP Traps XML-based APIs RingMaster Client Alarms/ Monitoring Configuration RingMaster Services Managed MXs

(3)

 RingMaster Agent allows the RingMaster 7.6 Web Services API to configure a list of SNMP targets (up to 4) and do basic RingMaster Agent configuration. The following information is included:

 Enable/Disable RM SNMP notification (global)  Basic SNMP Target Information (up to 4 targets)

− Target IP address − Port

− Community String − Filtering Criteria

> By severity: (Critical, Major, Minor, Info, All – Default: All)

> By category: (Client, Performance, Security, System, All – Default: All) You can select a combination of the above critieria. For example, you can select both Critical and Major, and Client and Security alarms. You can add, modify, or delete an SNMP target.

Advanced configuration includes:

 Updating interval (instant, 1 minute, 5 minutes, 15 minutes – Default 5 minutes)

RingMaster Agent buffers alarms based on the specified interval and forwards these alarms to specified SNMP targets only after the specified interval. This is designed to manage alarm bursting scenarios.

API Interface

The RingMaster 7.6 Web Services API provides a programmatic equivalent of the provisioning interface. It allows you to build your own interfaces or applications that use Internet technologies to access and manage RM alarms and device information.

An industry standard for providing Web Services is the REST (Representational State Transfer) architecture. Popular Web sites such as Yahoo Web Services and eBay Services are all using REST like architecture to provide services to the customized users for advertising and web searching.. See the following link for REST architecture and sample Yahoo Web services:

http://en.wikipe-dia.org/wiki/Representational_State_Transfer http://developer.yahoo.com/search/local/V3/localSearch.html

The idea behind REST is to locate a resource using a URI (Universal Resource Identifier). For example, it can use HTTP GET to download or retrieve a list of resources, a PUT or POST method to make a change to it, and DELETE method to remove it. The response will be in XML format and the schema can be

(4)

Access to the RingMaster 7.6 Web Services API is controlled via user name and password-based authentication. User names and passwords can be configured via the Administrative interface. Based on whether user privileges are set to the monitoring or provisioning level, a user can access the corresponding set of APIs. For the following WEB API, the monitoring privilege is required. Any privilege more than Monitoring can access ths Web API.

When the RingMaster 7.6 Web Services API is called via HTTP Request, the request should

embed/insert basic authorization in the HEADER. See the following link for a tutorial on Basic Authentication:

http://en.wikipedia.org/wiki/Basic_access_authentication

Licensing

The RingMaster 7.6 Web Services API is part of the separately licensed

RingMaster Agent feature. The license SKU for this feature is RMTS-AGENT, and it works just like the RMTS-PLAN license in that it requires that a base RMTS license be installed first.

License information is as follows:

When the RingMaster Agent license is not installed, RingMaster does not support the RingMaster 7.6 Web Services API, and a Code 403 Forbidden error is returned in this situation. In SNMP notification, when you click Notification, you will be notified that a RingMaster Agent license is missing and all functions for SNMP notification are disabled.

Web Services

The following is a list of Web services the RingMaster Agent provides. The RingMaster Agent publishes a list of Web API interfaces and the response XML schema in the release.

All Web request URLs start with the RingMaster Server IP Address and port, service name, version number, followed by a method name. The method is followed by query parameters, which take the form argument=value, where arguments and values are URL encoded. Multiple parameters are separated by an ampersand character (i.e. “&”).

Product Code SKU Description

02 RMTS Base license enabling support for up to 5 APs

and one switch.

(5)

For RM Agent 7.6, the command is updated to support the full access control privilege and the result has a new format where the result is divided into sections based on the privilege of the user group.

Get RM Agent version

Request URL:

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/version

Request Parameters:

This request has no parameters.  Response Schema:

Schema file:

agent-version.xsd

Request & Response Example:

Request: https://127.0.0.1 /webservice/rm-agent/v1/monitor/version  Response: <?xml version="1.0" encoding="UTF-8"?> <BUILD_NUMBER>7.0.1.0</ BUILD_NUMBER> <BUILD_DATE>2001-01-01</BUILD_DATE> <PRODUCT_NAME>RingMaster</PRODUCT_NAME> <PRODUCT_SHORT_NAME>RM</PRODUCT_SHORT_NAME> </VERSION>  Comments:

The BUILD_DATE is short format, MM/DD/YY.

Get a list of current alarms

Request URL:

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/current-alarms?scope=al l(equipment||planning)

Request Parameters:

The “scope” parameter is required, and the value of the scope must be all, equipment, or rf-planning.

Request & Response Example:

Request:

https://127.0.0.1 /webservice/rm-agent/v1/current-alarms?scope%3Dall

Response:

xmlns=”http://trapezenetworks.com/rm_current_alarms” time=”09-03-30 16:09:46”> <VIEW name=”monitor” scope=”equipment”>

(6)

<CATEGORY-COUNTS>

<CATEGORY name="Client" critical="0" major="0" minor="0"

info="0" total="0" />

<CATEGORY name="Performance" critical="0" major="0" minor="0"

info="0" total="0" />

<CATEGORY name="Security" critical="0" major="0" minor="0"

info="79" total="79" />

<CATEGORY name=”Client” critical=”0” major=”0” minor=”0” info=”0” total=”0”/>

<CATEGORY name="System" critical="1" major="0" minor="0"

info="0" total="1" />

<CATEGORY name="Total" critical="1" major="0" minor="0"

info="79" total="80" /> </CATEGORY-COUNTS>

<TYPE-COUNTS>

<TYPE name=”AP Fingerprint Check” category=”0” severity=”0” active=”1” cleared=”0” />

<TYPE name="AP Status Alarm" count="1" sever-ity=”0”

active=”0” cleared=”0”/>

<TYPE name=”Ad-hoc User Detected” category=”3” severity=”3” active=”0” cleared=”0” />

<TYPE name=”Low RSSI” category=”1” severity=”1” active=”1” cleared=”0” />

<TYPE name=”Low SNR” category=”1” severity=”1” active=”1” cleared=”0” />

<TYPE name="Suspect AP Detected" category=”3” severity=”3”

active=”50” cleared=”9” />

<TYPE name="total" count="80" /> </TYPE-COUNTS>

<SECURITY-COUNTS> <DOS />

<IDS>

<SECURITY-COUNT name="Suspect AP Detected" count="50" /> <SECURITY-COUNT name="Ad-hoc User Detected" count="1" /> </IDS>

</SECURITY-COUNTS> </VIEW>

- <VIEW name="monitor" scope="rf-planning"> - <CATEGORY-COUNTS>

<CATEGORY name="System" critical="1" major="0" minor="0" info="1" total="2" />

<CATEGORY name="Performance" critical="0" major="0" minor="13" info="0" total="13" />

<CATEGORY name="Client" critical="0" major="0" minor="0" info="0" total="0" />

<CATEGORY name="Security" critical="0" major="6" minor="0" info="12" total="18" />

<CATEGORY name="Total" critical="1" major="6" minor="13" info="13" total="33" />

</CATEGORY-COUNTS> <TYPE-COUNTS>

<TYPE name="AP Status Alarm" category="0" severity="0" active="1" cleared="6" />

(7)

<TYPE name="Ad-hoc User Detected" category="3" severity="3" active="4" cleared="22" />

<TYPE name="Low RSSI" category="1" severity="1" active="4" cleared="6" /> <TYPE name="Low SNR" category="1" severity="1" active="9" cleared="3" /> <TYPE name="Power Supply Status Check" category="0" severity="0"

active="1" cleared="0" />

<TYPE name="Rogue AP Client Detected" category="3" severity="3" active="2" cleared="7" />

<TYPE name="Suspect AP Detected" category="3" severity="3" active="12" cleared="23" />

</TYPE-COUNTS> - <SECURITY-COUNTS> <DOS />

- <IDS>

<SECURITY-COUNT name="Rogue AP Client Detected" count="2" /> <SECURITY-COUNT name="Suspect AP Detected" count="12" /> <SECURITY-COUNT name="Ad-hoc User Detected" count="4" /> </IDS>

</SECURITY-COUNTS> </VIEW>

</ALARMS-SUMMARY> </ALARMS-SUMMARY>

Get a list of current alarms with query criteria

Request URL:

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/current-alarms?scope=al l(or equipment or rf-planning)&op=query&type=client&ssid=trpz-wlan

Request Parameters:

Request & Response Example:

Request:

Parameter Value Description scope All|equipment|rf-planning Sample:scope=all

op

query To query a different sets of alarms based on the query criteria

Sample: op=query

Time_start

All | time (option) If this item ignored, the meaning is “all”

The time format must like yy-mm-dd hh:mm:ss,

Sample: time_start=07-11-29 23:20:47

time_end All | time (option) See above.

Type system|performance|client |security|all (required) Sample 1: type=system Sample 2: type=system&type=client&type=performance severity critica|major|minor|info|all (required) Sample 1: type=minor Sample 2: severity=critical&severity=major state All|active|acknowledged |cleared|deleted (required)

Sample 1: state =active

(8)

https://127.0.0.1/webservice/rm-agent/v1/monitor/current-alarms?scope%3Dall%26op% 3Dquery%26%20type%3DSystem%26severity%3Dcritical,info%26time_start%3D08-11-12%2012:12:12%26

Response:

<Alarms_Details time="09-06-19 12:47:06"> <VIEW name="monitor" scope="equipment"> <ALARM_LIST count="1">

<ALARM alarmObject="MX-216(2)" category="System" desc="Power Sup-ply 2 is Missing or Failed" lastUpdateTime="09-06-19 12:46:14" state="Active" severity="Info">

</ALARM> </ALARM_LIST> </VIEW>

<VIEW name="monitor" scope="rf-planning"> <ALARM_LIST count="16">

<ALARM alarmObject="AP5:AP-1-10" category="System" desc="AP: AP5:AP-1-10 with serial number (0674800352) is Down" lastUpdate-Time="09-06-19 12:22:51" state="Active" severity="Critical"> </ALARM>

<ALARM alarmObject="AP6:AP06" category="System" desc="AP: AP6:AP06 with serial number (0890201321) is Down" lastUpdate-Time="09-06-19 12:22:51" state="Active" severity="Critical"> </ALARM>

<ALARM alarmObject="AP1:AP(22)" category="System" desc="AP: AP1:AP(22) with serial number (0671501441) is Down" lastUpdate-Time="09-06-19 12:22:51" state="Active" severity="Critical"> </ALARM>

<ALARM alarmObject="MX-20(1)" category="Security" desc="A Suspect AP, MAC: 00:0b:0e:24:40:84 (Trapeze), SSID: symbio_guest, Radio </ALARM_LIST>

</VIEW> </Alarms_Details>

If you wish to continue with the query, you must narrow the scope of the query criteria.

Get list of device inventory

The following is a sample query URI for retrieving a list of MXs and access points:  Request URL:

https://127.0.0.1/webservice/rm-agent/v1/monitor/devices?scope=all(equipment||rf-plann ing)

Request Parameters:

The parameter, “scope”, is required. .

Request & Response Example:

Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/devices%3Dall

Response:

If the query results in more than 5000 alarms, the response only returns the last 5K alarms. The sort item is lastUpdateTime.

(9)

<?xml version="1.0" encoding="UTF-8"?> <DEVICES time="09-03-30 11:36:29">

<VIEW name="configure" scope="equipment">

<DEVICE mac_address="00:0B:0E:56:0F:1A" model="MXR-2" system_ip="172.31.177.77/27" sw_version="7.0.7.3.0" location="&quot;&quot;" name="MXR2-77" license="Access Points:4" object-id="com.trapeze.appl.shared.mdl.Chas-sis: 397" contact="" serial_number="0791600540" /> <DEVICE mac_address="00:00:00:00:00:00" model="MP-422" system_ip="" name="MXR277-AP01" object-id="com.trapeze.appl.shared.mdl.Distrib-utedAP: 826" serial_number="123"> <RADIOS_INFO radio_1_type="802.11b "radio_2_mac_address="00:00:00:00:00:00" radio_2_type="802.11b "radio_1_mac_address="00:00:00:00:00:00" /> </DEVICE> </VIEW>

<VIEW name="configure" scope="rf-planning"> <DEVICE mac_address="00:00:00:00:00:00" model="MP-422" system_ip="" name="AP-L1-a1-2.4G~-1" object-id="com.trapeze.appl.shared.mdl.Distrib-utedAP: 5097" serial_number="auto-rfplan-5097"> <RADIOS_INFO radio_1_type="802.11b" radio_2_mac_address="00:00:00:00:00:00" radio_2_type="802.11b" radio_1_mac_address="00:00:00:00:00:00" /> </DEVICE> <DEVICE mac_address="00:0B:0E:3A:CD:42" model="MX-200" system_ip="172.31.177.200/27" sw_version="7.0.7.3.0" location="&quot;&quot;" name="MX-200(1)" license="Access Points:32" object-id="com.trapeze.appl.shared.mdl.Chas-sis: 3401" contact="" serial_number="0624800034" /> </VIEW> </DEVICES>

Client Summary

Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/client-summary?scope= all(equipment||rf-planning)  Request Parameters

(10)

"scope" parameter is required, the value of the scope must be all, equipment or rf-planning.

Access Control Scope Monitor privilege

Request & Response Example

Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/client-summary?scope%3Dall

Response:

<CLIENT-SUMMARY

xmlns="http://www.trapezenetworks.com/rm_client_summary"> <VIEW name="monitor" scope="equipment">

<CLIENTS-BY-SSID>

<SSID name="zxc" count="1" /> </CLIENTS-BY-SSID>

<CLIENTS-BY-ACCESSTYPE>

<ACCESS-TYPE name="DOT1X" count="1" /> </CLIENTS-BY-ACCESSTYPE>

<CLIENS-BY-RADIOTYPE>

<RADIO-TYPE name="802.11g" count="1" /> </CLIENS-BY-RADIOTYPE>

</VIEW >

<VIEW name="monitor" scope="rf-planning"> <CLIENTS-BY-SSID>

<SSID name="zxc" count="1" /> </CLIENTS-BY-SSID>

<CLIENTS-BY-ACCESSTYPE>

<ACCESS-TYPE name="DOT1X" count="1" /> </CLIENTS-BY-ACCESSTYPE>

<CLIENS-BY-RADIOTYPE>

<RADIO-TYPE name="802.11g" count="1" /> </CLIENS-BY-RADIOTYPE> </VIEW> </CLIENT-SUMMARY>

Statistics

Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/statistics?scope=all(equi pment||rf-planning)&time= xxx  Request Parameters

(11)

 The value of the scope must be all, equipment or rf-planning.

 The time is to represent the specified number of seconds since the standard base time known as "the epoch", namely January 1, 1970, 00:00:00 GMT.  Access Control Scope

Monitor privilege

Request & Response Example

Request: https://127.0.0.1/webservice/rm-agent/v1/monitor/statistics?scope%3Dall%26time%3D1 238400000  Response: <TIMESERIES-SUMMARY xmlns="http://www.trapezenetworks.com/rm_statistics"> - <VIEW name="monitor" scope="equipment">

<SESSION-STATISTICS authorizedClients="0" clientDot1xErrors="0" clientAssocErrors="0" clientAuthenErrors="0" clientAuthorErrors="0" /> <TRAFFIC-STATISTICS octetIn="120237" octetOut="109197" octetTotal="229434" time="1238400000" />

</VIEW>

- <VIEW name="monitor" scope="rf-planning">

<SESSION-STATISTICS authorizedClients="1" clientDot1xErrors="0" clientAssocErrors="0" clientAuthenErrors="0" clientAuthorErrors="0" /> <TRAFFIC-STATISTICS octetIn="60117" octetOut="54597"

octetTotal="114714" time="1238400000" /> </VIEW> </TIMESERIES-SUMMARY>

Status Summary

Request URL https://<RingMasterServerIP>/webservice/rm-agent /v1/monitor/status-summary?scope=all(equipment||rf-planning)  Request Parameters

"scope" parameter is required.  Access Control Scope

Monitor privilege

Request & Response Example

Request:

https://127.0.0.1/webservice/rm-agent /v1/monitor/status-summary?scope%3Dall

Response:

<STATUS-SUMMARY

(12)

<VIEW name="monitor" scope="equipment">

<MXS down="0" up="5" disabled="0" unknown="0" /> <APS down="3" up="1" disabled="0" unknown="0" /> <RADIOS down="5" up="2" disabled="0" unknown="0" /> </VIEW>

<VIEW name="monitor" scope="rf-planning">

<MXS down="0" up="1" disabled="0" unknown="0" /> <APS down="1" up="0" disabled="0" unknown="0" /> <RADIOS down="2" up="0" disabled="0" unknown="0" /> </VIEW> </STATUS-SUMMARY>

Summary

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/summary?scope=all(equ ipment||rf-planning)  .Request Parameters

"scope" parameter is required, the value of the scope must be all, equipment or rf-planning

 Access Control Scope Monitor privilege

Request & Response Example

 Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/summary?scope%3Dall

 Response:

- <MONITOR-SUMMARY

xmlns="http://www.trapezenetworks.com/rm_monitor_summary"> - <VIEW name="monitor" scope="equipment">

- <ALARMS-SUMMARY> - <CATEGORY-COUNTS>

<CATEGORY name="System" critical="1" major="1" minor="0" info="0" total="2" />

<CATEGORY name="Performance" critical="0" major="0" minor="2" info="0" total="2" />

<CATEGORY name="Client" critical="0" major="0" minor="0" info="0" total="0" />

(13)

<CATEGORY name="Security" critical="0" major="1" minor="0" info="50" total="51" />

<CATEGORY name="Total" critical="1" major="2" minor="2" info="50" total="55" />

</CATEGORY-COUNTS> - <TYPE-COUNTS>

<TYPE name="AP Fingerprint Check" category="0" severity="0" active="1" cleared="0" />

<TYPE name="AP Status Alarm" category="0" severity="0" active="1" cleared="0" />

<TYPE name="Ad-hoc User Detected" category="3" severity="3" active="1" cleared="9" />

<TYPE name="Low RSSI" category="1" severity="1" active="1" cleared="0" />

<TYPE name="Low SNR" category="1" severity="1" active="1" cleared="0" /> <TYPE name="Suspect AP Detected" category="3" severity="3" active="50" cleared="9" />

</TYPE-COUNTS> - <SECURITY-COUNTS> <DOS />

- <IDS>

<SECURITY-COUNT name="Suspect AP Detected" count="50" /> <SECURITY-COUNT name="Ad-hoc User Detected" count="1" /> </IDS>

</SECURITY-COUNTS> </ALARMS-SUMMARY> - <CLIENT-SUMMARY> - <CLIENTS-BY-SSID>

<SSID name="ssid-belinda1" count="1" /> </CLIENTS-BY-SSID>

- <CLIENTS-BY-ACCESSTYPE>

<ACCESS-TYPE name="DOT1X" count="1" /> </CLIENTS-BY-ACCESSTYPE>

- <CLIENTS-BY-RADIOTYPE>

<RADIO-TYPE name="802.11g" count="1" /> </CLIENTS-BY-RADIOTYPE>

(14)

- <STATUS-SUMMARY>

<MXS down="0" up="1" disabled="0" unknown="0" /> <APS down="1" up="1" disabled="0" unknown="0" /> <RADIOS down="1" up="2" disabled="0" unknown="0" /> </STATUS-SUMMARY>

</VIEW>

- <VIEW name="monitor" scope="rf-planning"> - <ALARMS-SUMMARY>

- <CATEGORY-COUNTS>

<CATEGORY name="System" critical="1" major="0" minor="0" info="1" total="2" />

<CATEGORY name="Performance" critical="0" major="0" minor="13" info="0" total="13" />

<CATEGORY name="Client" critical="0" major="0" minor="0" info="0" total="0" />

<CATEGORY name="Security" critical="0" major="6" minor="0" info="13" total="19" />

<CATEGORY name="Total" critical="1" major="6" minor="13" info="14" total="34" />

</CATEGORY-COUNTS> - <TYPE-COUNTS>

<TYPE name="AP Status Alarm" category="0" severity="0" active="1" cleared="6" />

<TYPE name="Ad-hoc User Detected" category="3" severity="3" active="4" cleared="22" />

<TYPE name="Low RSSI" category="1" severity="1" active="4" cleared="6" />

<TYPE name="Low SNR" category="1" severity="1" active="9" cleared="3" /> <TYPE name="Power Supply Status Check" category="0" severity="0" active="1" cleared="0" />

<TYPE name="Rogue AP Client Detected" category="3" severity="3" active="2" cleared="7" />

<TYPE name="Suspect AP Detected" category="3" severity="3" active="13" cleared="22" />

</TYPE-COUNTS> - <SECURITY-COUNTS> <DOS />

(15)

- <IDS>

<SECURITY-COUNT name="Rogue AP Client Detected" count="2" /> <SECURITY-COUNT name="Suspect AP Detected" count="13" /> <SECURITY-COUNT name="Ad-hoc User Detected" count="4" /> </IDS> </SECURITY-COUNTS> </ALARMS-SUMMARY> - <CLIENT-SUMMARY> <CLIENTS-BY-SSID /> <CLIENTS-BY-ACCESSTYPE /> <CLIENTS-BY-RADIOTYPE /> </CLIENT-SUMMARY> - <STATUS-SUMMARY>

<MXS down="0" up="0" disabled="0" unknown="0" /> <APS down="0" up="0" disabled="0" unknown="0" /> <RADIOS down="0" up="0" disabled="0" unknown="0" /> </STATUS-SUMMARY> </VIEW> </MONITOR-SUMMARY>

Server Status

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/server-status  Request Parameters Not applicable.  Access Control Scope

Not applicable.

Request & Response Example

 Request: https://127.0.0.1/webservice/rm-agent/v1/monitor/server-status  Response: <?xml version="1.0" encoding="UTF-8"?> <SERVER-STATUS xmlns="http://www.trapezenetworks.com/rm_server_status" BUILD-NUMBER="7.6.0.0.266" BUILD-DATE="03/10/11" PRODUCT-NAME="RingMaster"

(16)

PRODUCT-SHORT-NAME="RingMaster" PLAN-NAME="Default" UPTIME="71535489"

HOST-NAME="lchcan2"></SERVER-STATUS>

Comments: the BUILD_DATE is in the short format, as MM/DD/YY.

Devices Summary

 Request URL

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ devices-summary?scope=all(equipment||rf-planning)

 Request Parameters

"scope" parameter is required. (The value of the scope must be all, equipment or rf-planning)

 Access Control Scope View privilege

Request & Response Example

 Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/devices-summary?scope%3Dall

 Response:

<DEVICES-SUMMARY

xmlns="http://www.trapezenetworks.com/rm_devices_summary"> <VIEW name="configure" scope="equipment">

<MXS>

<MX model="MXR-2" managed="2" unmanaged="0"/> </MXS>

<APS>

<AP model="MP-71" managed="1" unmanaged="0"/> <AP model="MP-432" managed="3" unmanaged="0"/> <TOP-MX-BY-CLIENTS>

<MX name="mx1" AuthorizedClients="1" Throughput="67648" TxMulticastOctets="15806167" TxUnicastOctets="24099258" RxOctets="134007619" Traffic="173913044" ApLocation="0" /> </TOP-MX-BY-CLIENTS>

<TOP-MX-BY-TRAFFIC>

<MX name="mx1" AuthorizedClients="1" Throughput="67648" TxMulticastOctets="15806167" TxUnicastOctets="24099258" RxOctets="134007619" Traffic="173913044" ApLocation="0" /> </TOP-MX-BY-TRAFFIC>

(17)

</VIEW>

<VIEW name="monitor" scope="rf-planning" /> </TOP-SUMMARY>

Find MX

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-mx?scope=equipment&name=xxx&ip-address=xxx&serial-number=xxx&status=xxx.  Request Parameters

Scope is always set to "equipment". If no search criteria is provided, all results are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/find-mx?scope%3Dequipment

 Response:

<FIND-MX xmlns="http://www.trapezenetworks.com/rm_find_mx" tooManyMatches="false" limitedAccess="true">

<VIEW name="monitor" scope="equipment">

<Device object-id="Mobility Exchange:1734" name="MXR2-76"

ip-address="172.31.177.76" serial-number="0621800238" model="MXR-2" status="Up" />

<Device object-id="Mobility Exchange:397" name="MXR2-77"

ip-address="172.31.177.77" serial-number="0791600540" model="MXR-2" status="Up" />

<Device object-id="Mobility Exchange:5954" name="mx1"

ip-address="172.31.177.39" serial-number="0525200128" model="MXR-2" status="Up" /> </VIEW> </FIND-MX>

Find AP

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-AP?scope=equipment&name=xxx&ip-address=xxx&serial-number=xxx&model=xxx.  Request Parameters

(18)

Scope is always set to "equipment". If no search criteria is provided, all results are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/find-AP?scope%3Dall

 Response:

<FIND-AP xmlns="http://www.trapezenetworks.com/rm_find_ap" tooManyMatches="false" limitedAccess="true">

<VIEW name="all" scope="equipment">

<DEVICE object-id="Distributed AP:826" name="MXR277-AP01" serial-number="123" model="MP-422" status="Down" />

<DEVICE object-id="Distributed AP:6410" name="AP01" serial-number="0674600143" model="MP-422" status="Up" /> <DEVICE object-id="Distributed AP:6419" name="AP05" serial-number="33323233" model="MP-71" status="Down" /> </VIEW> </FIND-AP>

Find Site

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-site?scope=rf-planning&name=xxx  Request Parameters

Scope is always set to "rf-planning". If no search criteria is provided, all results are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request:

https://127.0.0.1/webservice/rm-agent/v1/monitor/find-site?scope%3Drf-planning

 Response:

<FIND-SITE xmlns="http://www.trapezenetworks.com/rm_find_site" tooManyMatches="false" limitedAccess="false">

(19)

<SITE object-id="Site:5072" name="SiteA" network-plan="YourPlan" /> </VIEW> </FIND-SITE>

Find Building

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-building?scope=rf-planning&name=xxx  Request Parameters

Scope is always set to "rf-planning". If no search criteria is provided, all results are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request

https://127.0.0.1/webservice/rm-agent/v1/monitor/find-building?scope%3Drf-planning:

 Response:

<FIND-BUILDING xmlns="http://www.trapezenetworks.com/rm_find_building" tooManyMatches="false" limitedAccess="true">

<VIEW name="monitor" scope="rf-planning">

<BUILDING object-id="Building:5080" name="Building1" network-plan="YourPlan" site="SiteA" /> </VIEW> </FIND-BUILDING>

Find Floor

 Request URL https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-floor?scope=rf-planning&name=xxx  Request Parameters

Scope is always set to "rf-planning". If no search criteria is provided, all results are returned.

 Access Control Scope Monitor privilege

Request & Response Example

(20)

https://127.0.0.1/webservice/rm-agent/v1/monitor/find-floor?scope%3Drf-planning:

 Response:

<FIND-FLOOR xmlns="http://www.trapezenetworks.com/rm_find_floor" tooManyMatches="false" limitedAccess="true">

<VIEW name="monitor" scope="rf-planning"> <FLOOR object-id="Floor:5082" name="Floor1"

network-plan="YourPlan" site="SiteA" building="Building1" /> </VIEW>

</FIND-FLOOR>

Find Outdoor Area

 Request URL

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/ find-outdoorarea?scope=rf-planning&name=xxx

 Request Parameters

Scope is always set to "rf-planning". If no search critiera is provided, all the outdoor areas are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request https://127.0.0.1/webservice/rm-agent/v1/monitor/find-outdoorarea?scope%3Drf-plannin g:  Response: <FIND-OutdoorArea xmlns="http://www.trapezenetworks.com/rm_find_outdoorarea" tooManyMatches="false" limitedAccess="true">

<VIEW name="monitor" scope="rf-planning">

<OUTDOORAREA object-id="Outdoor Area:15360" name="OA1" site="SiteA" network-plan="YourPlan" />

<OUTDOORAREA object-id="Outdoor Area:15366" name="OA2" site="SiteA" network-plan="YourPlan" />

</VIEW>

</FIND-OutdoorArea>

Find Client

(21)

https://<RingMasterServerIP>/webservice/rm-agent/v1/monitor/find-client?

scope=all(equipment||rf-planning)&user-name=xxx&mac-address=xxx&ip-address=xxx.

 Request Parameters

Scope is one of "equipment | rf-planning | all".

Besides scope, at least one of the search critieral must be provided.  Access Control Scope

Monitor privilege

Request & Response Example

 Request: https://127.0.0.1/webservice/rm-agent/v1/monitor/find-client? scope%3Dall%26user-name%3Dbelinda1  Response: <FIND-CLIENT-RESULT xmlns="http://www.trapezenetworks.com/find_client" tooManyMatches="false" limitedAccess="true"> <VIEW name="monitor" scope="equipment">

<USER-SESSION session-id="SESS-295-310934-376258-96b8a" user-name="belinda1" ip-addr="172.31.177.51"

mac-addr="00:1b:11:e8:d3:ab" ssid="ssid-belinda1"

session-state="ACTIVE" start-time="1238376258000" access-type="DOT1X" auth-server="172.31.176.23" auth-protocol="PASSTHRU"

collected-time="1238399317824" op-rate="36" snr="48" rssi="-47"  Request Parameters

Scope is always set to "rf-planning". If no search critiera is provided, all the outdoor areas are returned.

 Access Control Scope Monitor privilege

Request & Response Example

 Request https://127.0.0.1/webservice/rm-agent/v1/monitor/find-outdoorarea?scope%3Drf-plannin g:  Response: <FIND-OutdoorArea xmlns="http://www.trapezenetworks.com/rm_find_outdoorarea" tooManyMatches="false" limitedAccess="true">

(22)

<OUTDOORAREA object-id="Outdoor Area:15360" name="OA1" site="SiteA" network-plan="YourPlan" />

<OUTDOORAREA object-id="Outdoor Area:15366" name="OA2" site="SiteA" network-plan="YourPlan" /> </VIEW> </FIND-OutdoorArea> device-ip-address="172.31.177.39" device-name="mx1" device-obj-id="Mobility Exchange:5954" radio-obj-id="ProductSpecific Radio:6413" device-enable-pwd="00141215174c04140b" device-authmode="LEGACY" /> </VIEW>

<VIEW name="monitor" scope="rf-planning">

<USER-SESSION session-id="SESS-295-310934-376258-96b8a" user-name="belinda1" ip-addr="172.31.177.51"

mac-addr="00:1b:11:e8:d3:ab" ssid="ssid-belinda1"

session-state="ACTIVE" start-time="1238376258000" access-type="DOT1X" auth-server="172.31.176.23" auth-protocol="PASSTHRU"

collected-time="1238399317824" op-rate="36" snr="48" rssi="-47" device-ip-address="172.31.177.39" device-name="mx1" device-obj-id="Mobility Exchange:5954" radio-obj-id="ProductSpecific Radio:6413" device-enable-pwd="00141215174c04140b" device-authmode="LEGACY" /> </VIEW> </FIND-CLIENT-RESULT>

Error Handling

The RingMaster 7.6 Web Services API returns standard HTTP errors. The following errors have been identified:

 Code 400: Bad request  Code 403: Forbidden

 Code 503: Service Unavailable

When an error is returned, the following XML fragment is passed in the HTML body:

<ERROR>

<MESSAGE>The error message</MESSAGE> </ERROR>

References

Download now ( PDF - 22 Page - 407.38 KB )

Related documents