Table Of Contents
Using the VNMC XML API
Tutorial Examples
Authentication Methods
Login
Query Methods
Using configResolveDn
Using configResolveDns
Using configResolveClass
Using configResolveClasses
Using configFindDnsByClassId
Using configResolveChildren
Using configResolveParent
Using configScope
Using Query Methods for Policies
Querying Faults
Using Filters
Simple Filters
Property Filters
Composite Filters
Modifier Filter
VNMC XML API Use Case Example
Authentication via Management Controller
Login
Tenant Management via Service Registry
Policy Management
Device Policy
Device Profile
Zone
Object Group
Attribute Dictionary
Policy
PolicySet
Security Profile
Resource Management
Compute Firewall
Query Firewall Instances
Associate Firewall Instance
Using the VNMC XML API
This chapter includes the following:
•Tutorial Examples
•VNMC XML API Use Case Example
API method details are provided below.
Tutorial Examples
This section contains the following topics:
•Authentication Methods
•Query Methods
•Using Query Methods for Policies
•Using Filters
Authentication Methods
Authentication allows API interaction with VNMC. It also provides a way to set permissions and control the operations that can be performed.
Note A session cookie is a 47-character string; it is not the type of cookie that web browsers store locally to maintain session information. Most code examples use "<real_cookie>" for an actual cookie (such as 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf).
Login
The following example uses a Linux POST command to post authentication requests, using HTTPS to VNMC.
POST https://10.193.34.70/xmlIM/mgmt-controller
Please enter content (application/x-www-form-urlencoded) to be POSTed:
Then use aaaLogin and provide a username and password:
Note The XML version and DOCTYPES are not present and should not be used. The inName and inPassword attributes are parameters.
Each XMLAPI document represents an operation to be performed. When the request is received as an XML API document, VNMC reads the request and performs the actions as provided in the method. VNMC responds with a message in XML document format and indicates success or failure of the request.
The following is a typical successful response:
(3) outCookie="<real_cookie>"
(4) outRefreshPeriod="600"
(5) outPriv="admin,read-only"
(6) outDomains="mgmt02-dummy"
(8) outEvtChannel="fullssl">
(1) The method used to login.
(2) Confirms this is a response.
(3) This is the session cookie.
(4) The recommended cookie refresh period. The default login session length is two hours.
(5) The privileges assigned to the user account.
(6) The outDomains value is mgmt02-dummy.
(7) The outChannel value is fullssl (this session is using encryption over SSL).
(8) The outEvtChannel value is fullssl (any event subscriptions use encryption over SSL).
(9) Closing tag.
Note VNMC 1.0 event channel is using HTTP so it is neither encrypted nor over SSL
Refreshing the Session
Sessions are refreshed with aaaRefresh method, using the 47-character cookie obtained either from the aaaLogin response or a previous refresh.
inCookie="<real_cookie>"/>
Logging Out of the Session
Use the following method to log out of a session:
inCookie="<real_cookie>" />
Unsuccessful Responses
The following is the response to a failed login:
(5) invocationResult="unidentified-fail"
(6) errorDescr="Authentication failed">
(1) The method used to login. The VNMC sends a response message with the result from the method.
(2) Confirms this is a response.
(3) The VNMC does not supply a session cookie.
(4) (5) (6) Shows the error code and description.
(7) Closing tag
Query Methods
Query methods obtain information (that is, hierarchy, state, and scope)
This section contains the following topics:
•Using configResolveDn
•Using configResolveDns
•Using configResolveClass
•Using configResolveClasses
•Using configFindDnsByClassId
•Using configResolveChildren
•Using configResolveParent
•Using configScope
Using configResolveDn
When resolving a DN, note the following:
•The object specified by the DN is retrieved
•Specified DN identifies the object instance to be resolved (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
See the example request/response in configResolveDn, page 3-22.
Using configResolveDns
When resolving multiple DNs, note the following:
•The objects specified by the DNs are retrieved
•Specified DN identifies the object instance to be resolved (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
•Order of a request does not determine the order of the response
Unknown DNs are returned as part of the outUnresolved element.
See the example request/response in configResolveDns, page 3-24.
Using configResolveClass
When resolving a class, note the following:
•All objects of the specified class type are retrieved
•classId specifies the object class name to return (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
Result sets can be large. Be precise when defining result sets. For example, to obtain only a list of servers, use computeBlade as the attribute value for classId in the query. To get all instances of equipment, query the equipmentItem class. This queries for all instances of the class equipmentItem:
See the example request/response in configResolveClass, page 3-20.
Using configResolveClasses
When resolving multiple classes, note the following:
•This retrieves all the objects of the specified class types
•classId attribute specifies the name of the object class to return (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
If an invalid class name is specified in the inId attribute, an XML parsing error is generated. The query cannot execute.
See the example request/response in configResolveClasses, page 3-21.
Using configFindDnsByClassId
When finding distinguished names of a specified class, note the following
•This retrieves the DNs of a specified class
•classId specifies the object type to retrieve (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
See the example request/response in configFindDnsByClassId, page 3-16.
Using configResolveChildren
When resolving children of objects in the management information tree, note the following:
•This obtains all child objects of a named object that are instances of the named class. If a class name is omitted, all child objects of the named object are returned.
•inDn attribute specifies the named object from which the child objects are retrieved (required).
•classId attribute specifies the name of the child object class to return (optional).
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
See the example request/response in configResolveChildren, page 3-18.
Using configResolveParent
When resolving the parent object of an object, note the following:
•This retrieves the parent object of a specified DN
•dn attribute is the DN of the child object (required)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
See the example request/response in configResolveParent, page 3-26.
Using configScope
Limiting the scope of a query allows for a finer grained, less resource-intensive request. The query can be anchored at a point in the management information tree other than the root. When setting the query scope, note the following:
•This sets the root (scope) of the query to a specified DN and returns objects of the specified class type
•dn is the named object from which the query is scoped (required)
•inClass attribute specifies the name of the object class to return (optional; when a class is not specified, the query acts the same as configResolveDn)
•Authentication cookie (from aaaLogin or aaaRefresh) is required
•inHierarchical attribute (default = false) if true, specifies that results are hierarchical
•Enumerated values, classIds, and bit masks are displayed as strings
The following example queries for the policies in the policy manager:
<configScope dn="sys/chassis-1"
Also see the example request/response in configScope, page 3-28.
Using Query Methods for Policies
Policies are available on different organizations. In a large system with many policies, querying all policies at once is resource intensive. Instead, identify the type of policy and the parent org on which the policies are attached. For example, use the following query to get all the rule based policies defined under a tenant with the dn " org-root/org-tenant_d3338",
dn="org-root/org-tenant_d3338"
inClass="policyRuleBasedPolicy" />
The response is as follows:
dn="org-root/org-tenant_d3338"
destExtSys="10.193.34.70"
dn="org-root/org-tenant_d3338/pol-p9"
dn="org-root/org-tenant_d3338/pol-p1"
Although, a query by the DN is more efficient:
dn="sys org-root/org-tenant_d3338/pol-p1">
To get the policy object and its rule data, change inHierarchical to true:
dn=" org-root/org-tenant_d3338/pol-p1">
Querying Faults
The following example obtains a list of major faults:
The following example (which contains the filter <inFilter>eq class= "faultInst") obtains a list of all major or critical faults:
property="highestSeverity"
Using Filters
Use filters to create specific and targeted queries. This section contains the following topics:
•Simple Filters
•Property Filters
•Composite Filters
•Modifier Filter
Simple Filters
Simple filters use true and false conditions of properties to select results.
False example
True example
Property Filters
Equality Filter
The example shows a query for all associated compute firewalls. The equality filter is framed as follows:
classId="fwComputeFirewall">
<eq class="fwComputeFirewall"
Not Equal Filter
The example finds all compute firewalls that are not associated. The filter is framed as follows:
classId="fwComputeFirewall">
<ne class="fwComputeFirewall"
Greater Than Filter
The example finds the memory arrays with more than 1024 MB capacity. The filter is framed as follows:
Greater Than or Equal to Filter
The example finds core dump files with size greater than 2MB. The filter is framed as follows:
Less Than Filter
The example finds core dumpfiles with size less than 2MB. The filter is framed as follows:
Less Than or Equal to Filter
The example finds core dump files with size less than orequals to 2MB. The filter is framed as follows:
Wildcard Filter
The wildcard filter uses standard regular expression syntax. The example finds any virtual firewalls whose name begins with the prefix "dmz":
<wcard class="fwInstance"
Any Bits Filter
The example finds all managed endpoints that have a capacity of either vm-fw or vm-vasw (the property capability is a bit mask). The filter is framed as follows:
<anybit class="extpolClient"
All Bits Filter
The example finds all service profiles with the capability bit mask set to both vm-fw and vm-slb. The filter is framed as follows:
<allbits class="extpolClient"
Composite Filters
AND Filter
To finad all computer firewalls that are associated with configuration properly applied, run the following query:
classId="fwComputeFirewall">
<eq class="fwComputeFirewall"
<eq class="fwComputeFirewall"
OR Filter
The example returns all managed endpoints whose operational state is either "lost-visibility" or "unregistered".
value="lost-visibility"/>
Between Filter
The example finds the memory arrays with slots 1, 2, 3, 4, or 5 populated (note that the between range is inclusive). The filter is framed as follows:
AND, OR, NOT Composite Filter
The example is an AND, OR, NOT combination. It returns all objects of type computeBlade that are located in slot one or slot eight from all chassis, except chassis five.
Modifier Filter
NOT Filter
The NOT filter can negate a contained filter. The example below queries for managed endpoints that do not have a capability of "vm-fw" (the property capability is a bit mask):
<anybit class="extpolClient"
VNMC XML API Use Case Example
This use case is provided to enable API developers to have an example on using the VNMC XML API to configure and manage the VNMC application.
This use case example is divided into these sections with the ordering of sections representing the workflow:
•Authentication via Management Controller
•Tenant Management via Service Registry
•Policy Management
•Resource Management
Authentication via Management Controller
Login
Access to the VNMC is session-based and must first be authenticated with a login request. Default session lengths are 120 minutes. Sessions can be extended with the aaaKeepAlive and aaaRefresh methods. It is recommended that when activity is completed that the user manually log out of the session using aaaLogout.
Use service type 'mgmt-controller' to send your login request to VNMC.
Request
POST URL: https://10.193.33.221/xmlIM/mgmt-controller
Response
outCookie="<real_cookie>"
outPriv="admin,read-only"
Tenant Management via Service Registry
The Service Registry (service type 'service-reg') is used to create and manage tenants and the sub-organizations which are used to organize the policies and resources under a tree hierarchy for the bottom-up based policy and resource resolution. Class names used in tenant and its sub-org creation VNMC supports the following four level organization hierarchies:
•Tenant (class: orgTenant)—Top level organization to define a tenant
•DataCenter (class: orgDatatcenter)—defines data centers under a tenant
•App (class: orgApp)—Defines applications under a data center
•Tier (class: orgTier)—Defines the application tiers (web, db, app) that a VM runs
To create a new or update an existing org object, provide the object's DN and attribute values and use status "created" or "modified" respectively. To delete an org object, use status="deleted" in the request. The request shows how to create a tenant named demoTenant.
Request
POST URL: https://10.193.33.221/xmlIM/service-reg
<pair key="org-root/org-demoTenant">
<orgTenant dn="org-root/org-demoTenant"
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
destSvc="service-reg_dme"
<pair key="org-root/org-demoTenant">
dn="org-root/org-demoTenant"
Policy Management
The API sample payloads have been taken from their usage in the VNMC GUI application.
In each example where configConfMos API used a single XML element <pair> to specify a single configuration object, as an alternative, the configConfMo API can be used to obtain the same result.
This section includes the following topics:
•Device Policy
•Device Profile
•Zone
•Object Group
•Attribute Dictionary
•Policy
•PolicySet
•Security Profile
Device Policy
These actions establish various policies that include:
• Syslog
• SNMP
• LogProfile
Syslog
Description
The syslog policy object tracks all actions that take place within the system. It sets the logging level for a device policy. This creates mysyslog.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<inConfigs>
<pair key="org-root/syslog-mysyslog">
<commSyslog dn="org-root/syslog-mysyslog">
forwardingFacility="local7"/>
forwardingFacility="local5"/>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/syslog-mysyslog">
dn="org-root/syslog-mysyslog"
SNMP
This example creates a SNMP policy named mysnmp. Once created, this will be available by that name in the device profile listing.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/snmp-mysnmp">
<commSnmp dn="org-root/snmp-mysnmp"
descr="The default SNMP policy"
sysContact="Andrew Jackson"
hostname="nms-1.cisco.com"
hostname="nms-2.cisco.com"
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/snmp-mysnmp">
descr="The default SNMP policy"
dn="org-root/snmp-mysnmp"
sysContact="Andrew Jackson"
LogProfile
This example sets the debug level for a LogProfile policy named debugLog. It sets the logging level.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/logprof-default">
dn="org-root/logprof-debugLog"
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/logprof-debugLog">
descr="the log level for every process"
dn="org-root/logprof-debugLog"
Device Profile
This action creates a device profile named myDeviceProfile. It enables the profile and designates the contents of the profile.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-Cola/fwdevprofile-myDeviceProfile">
<fwpolicyFirewallDeviceProfile
dn="org-root/org-Cola/fwdevprofile-myDeviceProfile"
timezone="America/Los_Angeles" >
<!-- The order means the device should first use the DNS provider with the smallest
"order" value. If that DNS server is not responsive, use the DNS provider with the next
smaller number. -->
name="north-america.pool.ntp.org"
</fwpolicyFirewallDeviceProfile>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-Cola/fwdevprofile-myDeviceProfile">
<fwpolicyFirewallDeviceProfile
dn="org-root/org-Cola/fwdevprofile-myDeviceProfile"
enablePolicyDecisionLog="no"
timezone="America/Los_Angeles"/>
Zone
This creates two zones named trustedClients-0 and trustedServers-0. A set of attributes with values are also assigned.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-Cisco/zone-trustedClients-0">
<!-- Create a zone of all VMs in the 192.168.1.0/24 subnet -->
<policyZone dn="org-root/org-Cisco/zone-trustedClients-0">
<policyZoneCondition id="1" order="1">
<policyZoneExpression opr="prefix">
<policyIPAddress id="1" value="192.168.1.0" />
<policyIPSubnet id="1" value="255.255.255.0" />
<pair key="org-root/org-Cisco/zone-trustedServers-0">
<!-- Create a zone of all VMs attached to a VNSP where the "appType" is set to
"BuildServer" -->
<policyZone dn="org-root/org-Cisco/zone-trustedServers-0">
<policyZoneCondition id="1" order="1">
<policyZoneExpression opr="eq">
<policyParentAppName id="1" value="BuildServer" />
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-tenant0/zone-zone0">
dn="org-root/org-tenant0/zone-zone0"
<pair key="org-root/org-Cisco/zone-trustedServers-0">
dn="org-root/org-Cisco/zone-trustedServers-0"
<pair key="org-root/org-Cisco/zone-trustedClients-0">
dn="org-root/org-Cisco/zone-trustedClients-0"
Object Group
This example creates an object group named ftpPorts0 and assigns a set of attributes.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-tenant0/objgrp-ftpPorts0">
<policyObjectGroup dn="org-root/org-tenant0/objgrp-ftpPorts0">
<policyObjectGroupExpression id="1" order="1" opr="eq">
<policyNetworkPort id="1" value="20" />
</policyObjectGroupExpression>
<policyObjectGroupExpression id="2" order="2" opr="eq">
<policyNetworkPort id="1" value="21" />
</policyObjectGroupExpression>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-tenant0/objgrp-ftpPorts0">
dn="org-root/org-tenant0/objgrp-ftpPorts0"
Attribute Dictionary
This sets the dictionary that defines the various attribute IDs and name.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<!-- Create Sample VnspCustomDictionary under org-Cisco -->
<pair key="org-root/attr-dict-custom-userAttrs">
<policyVnspCustomDictionary dn="org-root/attr-dict-custom-userAttrs">
<policyVnspCustomAttr dataType="string" id="1" name="userAttr1" />
<policyVnspCustomAttr dataType="string" id="2" name="userAttr2" />
<policyVnspCustomAttr dataType="string" id="3" name="dept" />
<policyVnspCustomAttr dataType="string" id="4" name="production" />
</policyVnspCustomDictionary>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/attr-dict-custom-userAttrs">
<policyVnspCustomDictionary
dn="org-root/attr-dict-custom-userAttrs"
Policy
This creates a policy named trustedHosts and sets the rules it can use.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-Cisco/pol-trustedHosts">
<policyRuleBasedPolicy dn="org-root/org-Cisco/pol-trustedHosts">
<policyRule name="allowSsh" order="1">
<!-- This rule allows all VMs in zone "trustedClients" to initiate an SSH connection to
VMs in zone "trustedServers" -->
<policyRuleCondition id="100" order="1">
<policyNetworkExpression opr="eq">
<policyNwAttrQualifier attrEp="source"/>
<policyZoneNameRef id="1" value="trustedClients-0" />
</policyNetworkExpression>
<policyRuleCondition id="101" order="20">
<policyNetworkExpression opr="eq">
<policyNwAttrQualifier attrEp="destination"/>
<policyZoneNameRef id="1" value="trustedServers-0" />
</policyNetworkExpression>
<policyRuleCondition id="103" order="30">
<policyNetworkExpression opr="eq">
<policyNwAttrQualifier attrEp="destination"/>
<policyNetworkPort id="1" placement="0" value="22" />
</policyNetworkExpression>
<fwpolicyAction actionType="permit"/>
<policyRule name="allowTacacs" order="2">
<fwpolicyAction actionType="permit"/>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-Cisco/pol-trustedHosts">
dn="org-root/org-Cisco/pol-trustedHosts"
PolicySet
This creates myPolicySet0 and sets the order that policies are applied.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-tenant0/pset-myPolicySet0">
dn="org-root/org-tenant0/pset-myPolicySet0"
<!-- Policy Set contains references to three policies. Policies are resolved by name in
the org hierarchy. Ordering of policies is important, so we use the "order" property to
order the policies. Note that two policy sets can refer to the same policies, and use a
different order. -->
<policyPolicyNameRef order="1" policyName="trustedHosts"/>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-tenant0/pset-myPolicySet0">
dn="org-root/org-tenant0/pset-myPolicySet0"
Security Profile
This creates a security profile named vnsp-sp1, and assigns the VNSP to it.
Request
POST URL: https://10.193.33.221/xmlIM/policy-mgr
<pair key="org-root/org-tenant0/vnsp-sp1">
<policyVirtualNetworkServiceProfile
dn="org-root/org-tenant0/vnsp-sp1"
policySetNameRef="myPolicySet0">
<policyVnspAVPair id="1">
<policyAttributeDesignator attrName="dept"/>
<policyAttributeValue value="DEV" />
</policyVirtualNetworkServiceProfile>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
<pair key="org-root/org-tenant0/vnsp-sp1">
<policyVirtualNetworkServiceProfile
dn="org-root/org-tenant0/vnsp-sp1"
policySetNameRef="myPolicySet0"
Resource Management
This component performs the following functions:
• Assigns the compute firewall to a device policy.
• Queries for available firewall instances
• Associate firewall instances with a managed object
This section includes the following topics:
•Compute Firewall
•Query Firewall Instances
•Associate Firewall Instance
Compute Firewall
This assigns computeFirewall to a device policy..
Request
POST URL: https://10.193.33.221/xmlIM/resource-mgr
<pair key="org-root/org-Cisco/cfw-VSNaaa">
<fwComputeFirewall dn="org-root/org-Cisco/cfw-VSNaaa"
devicePolicy="myDeviceProfile"
dataIpAddress="10.10.10.100">
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
destSvc="resource-mgr_dme"
<pair key="org-root/org-Cisco/cfw-VSNaaa">
assocState="unassociated"
configState="not-applied"
dataIpAddress="10.10.10.100"
dataIpSubnet="255.255.255.0"
devicePolicy="myDeviceProfile"
dn="org-root/org-Cisco/cfw-VSNaaa"
Query Firewall Instances
This queries all firewall instances and their attributes.
Request
POST URL: https://10.193.33.221/xmlIM/resource-mgr
Response
configResolveClass
cookie=<real_cookie>"
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
destSvc="resource-mgr_dme"
fsmPrev="DisassociateSuccess"
fsmStamp="2010-12-03T23:18:13.304"
registeredClientDn="extpol/reg/clients/client-1005"
Associate Firewall Instance
This associates a firewall instance to a managed object.
This example assigns firewall-0 to the inst-1005.
Request
POST URL: https://10.193.33.221/xmlIM/resource-mgr
<pair key="org-root/org-Cola/cfw-firewall-0">
<fwComputeFirewall dn="org-root/org-Cola/cfw-firewall-0">
<fwResourceBinding assignedToDn="fw/inst-1005"/>
Response
srcExtSys="10.193.33.221"
destExtSys="10.193.33.221"
destSvc="resource-mgr_dme"
<pair key="org-root/org-Cola/cfw-firewall-0">
configState="not-applied"
dataIpAddress="168.1.1.221"
dataIpSubnet="255.255.255.0"
devicePolicy="myDeviceProfile"
dn="org-root/org-Cola/cfw-firewall-0"
hostname="cfw-firewall-0"