Cisco VNMC XML API Reference Guide, Release 1.3
Using the Cisco VNMC API
Downloads: This chapterpdf (PDF - 323.0KB) The complete bookPDF (PDF - 2.28MB) | Feedback

Using the Cisco VNMC XML API

Table Of Contents

Using the Cisco VNMC XML API

Methods and Filters

Authentication Methods

Login

Refreshing the Session

Logging Out of the Session

Response to a Failed Login

Query Methods for Information Gathering

Using configResolveDn

Using configResolveDns

Using configResolveClass

Using configResolveClasses

Using configFindDnsByClassId

Using configResolveChildren

Using configResolveParent

Using configScope

Query Methods for Policies

Query Methods for Faults

Filters

Simple Filters

Property Filters

Composite Filters

Modifier Filters

API Examples

Authentication Using the Management Controller

Authentication Request

Authentication Response

Tenant Management Using the Service Registry

Create or Update Organization Request

Create or Update Organization Response

Policy Management

Device Policies

Device Profiles

Zone

Object Group

Attribute Dictionary

Policy

PolicySet

Security Profile

Resource Management

Compute Firewall

Query Firewall Instances

Associate Firewall Instance


Using the Cisco VNMC XML API


This chapter includes the following sections:

Methods and Filters

API Examples

Methods and Filters

This section contains the following topics:

Authentication Methods

Query Methods for Information Gathering

Query Methods for Policies

Query Methods for Faults

Filters

Authentication Methods

Authentication allows API interaction with the Cisco 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.


This section contains the following topics:

Login

Refreshing the Session

Logging Out of the Session

Response to a Failed Login

Login

Example 2-1 uses a Linux POST command to post authentication requests, using HTTPS to connect to Cisco VNMC:

Example 2-1 Login Request

POST https://10.193.34.70/xmlIM/mgmt-controller
Please enter content (application/x-www-form-urlencoded) to be POSTed:
<aaaLogin 
	inName="admin" 
	inPassword="cisco@123"/>

Note The XML version and DOCTYPES are not included in aaaLogin and should not be used. The inName and inPassword attributes are parameters.


Each XML API document represents an operation to be performed. When the request is received as an XML API document, the Cisco VNMC reads the request and performs the actions as provided in the method. The Cisco VNMC responds with a message in XML document format and indicates success or failure of the request.

Example 2-2 shows a typical successful response:

Example 2-2 Login Request Response

<aaaLogin 
	response="yes" 
	outCookie="<real_cookie>" 
	outRefreshPeriod="600"
	outPriv="admin,read-only" 
	outDomains="mgmt02-dummy" 
	outChannel="fullssl" 
	outEvtChannel="fullssl"> 
</aaaLogin>

Note VNMC 1.0 event channel is using HTTP so it is neither is encrypted or transmitted over SSL


Refreshing the Session

Sessions are refreshed with the aaaRefresh method, using the 47 character cookie obtained either from the aaaLogin response or a previous refresh.

Example 2-3 is the method for refreshing a session:

Example 2-3 Refreshing a Session

<aaaRefresh 
	inName="admin" 
	inPassword="mypasword" 
	inCookie="<real_cookie>"/>

Logging Out of the Session

Example 2-4 is the method for logging out of a session:

Example 2-4 Logging Out of a Session

<aaaLogout 
	inCookie="<real_cookie>"/>

Response to a Failed Login

Example 2-5 is the response to a failed login:

Example 2-5 Resopnse to a Failed Login

<aaaLogin 
	response="yes" 
	cookie="" 
	errorCode="551" 
	invocationResult="unidentified-fail" 
	errorDescr="Authentication failed"> 
</aaaLogin>

Query Methods for Information Gathering

Query methods obtain information that includes 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, ensure the following:

The object specified by the DN is retrieved.

The specified DN identifies the object instance to be resolved and is required.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

See the example request/response in configResolveDn.

Using configResolveDns

When resolving multiple DNs, ensure the following:

The objects specified by the DNs are retrieved.

The specified DN identifies the object instance to be resolved.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

The order of a request does not determine the order of the response.

The unknown DNs are returned as part of the outUnresolved attribute.

See the example request/response in configResolveDns.

Using configResolveClass

When resolving a class, ensure the following:

The objects of the specified class type are retrieved.

The classId attribute specifies the object class name returned.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, 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.

See the example request/response in configResolveClass.

Using configResolveClasses

When resolving multiple classes, ensure the following:

The objects of the specified class type are retrieved.

The classId attribute specifies the object class name returned.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.


Note 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.

Using configFindDnsByClassId

When finding distinguished names of a specified class, ensure the following

The DNs of the specified class are retrieved.

The classId attribute specifies the object type to retrieve.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

See the example request/response in configFindDnsByClassId.

Using configResolveChildren

When resolving children of objects in the management information tree, ensure the following:

The method obtains all child objects of a named object that are instances of the named class.


Note If a class name is omitted, all child objects of the named object are returned.


The inDn attribute specifies the named object from which the child objects are retrieved.

The classId attribute specifies the name of the child object class to return.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

See the example request/response in configResolveChildren.

Using configResolveParent

When resolving the parent object of an object, ensure the following:

The method retrieves the parent object of a specified DN.

The dn attribute is the DN of the child object.

The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

See the example request/response in configResolveParent.

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, ensure the following:

The method sets the root (scope) of the query to a specified DN and returns objects of the specified class type.

The dn is the named object from which the query is scoped.

The inClass attribute specifies the name of the object class to return.


Note When a class is not specified, the query acts the same as configResolveDn.


The authentication cookie is received from aaaLogin or aaaRefresh.

The inHierarchical attribute (default = false), if true, specifies that the results are hierarchical.

The enumerated values, class IDs, and bit masks are displayed as strings.

See the example request/response in configScope.

Query Methods for Policies

Policies are available in 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 organization to which the policies are attached.

Example 2-6 shows queries for rule-based policies.

Example 2-6 Queries for Rule-Based Policies

<configScope 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	dn="org-root/org-tenant_d3338" 
	inClass="policyRuleBasedPolicy" /> 

The response is as follows:

<configScope
	dn="org-root/org-tenant_d3338"
	cookie="<real_cookie>"
	commCookie="7/13/0/24e7"
	srcExtSys="10.193.34.70"
	destExtSys="10.193.34.70"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<policyRuleBasedPolicy
			descr=""
			dn="org-root/org-tenant_d3338/pol-p9"
			intId="10274"
			name="p9"/>
		<policyRuleBasedPolicy
			descr=""
			dn="org-root/org-tenant_d3338/pol-p1"
			intId="10301"
			name="p1"/>
	</outConfigs>
</configScope> 

The following query using the DN is more efficient:

<configResolveDn 
	inHierarchical="false" 
	cookie="<real_cookie>" 
	dn="sys org-root/org-tenant_d3338/pol-p1"> 
</configResolveDn>  

To get the policy object and its rule data, change inHierarchical to true:

<configResolveDn 
	inHierarchical="true" 
	cookie="<real_cookie>" 
	dn=" org-root/org-tenant_d3338/pol-p1"> 
</configResolveDn>

Query Methods for Faults

Example 2-7 shows queries for faults.

Example 2-7 Queries for Faults

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="faultInst"/>
 
   

This example, which contains the filter <inFilter> eq class= "faultInst", obtains a list of all major or critical faults:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="faultInst">
	<inFilter>
		<eq class="faultInst" 
			property="highestSeverity" 
			value="major" />
	</inFilter>
</configResolveClass>

Filters

Use filters to create specific and targeted queries.

This section contains the following topics:

Simple Filters

Property Filters

Composite Filters

Modifier Filters

Simple Filters

Simple filters use true and false conditions.

This section contains the following topics:

False Conditions

True Conditions

False Conditions

This example shows a simple filter using false conditions:

<configResolveClass
	cookie="<real_cookie>"
	classId="topSystem"
	inHierarchical="false">
    <inFilter>
    </inFilter>
</configResolveClass>

True Conditions

This example shows a simple filter using true conditions:

<configResolveClass 
	cookie="<real_cookie>"
	classId="topSystem"
	inHierarchical="true">
	<inFilter>
	</inFilter>
</configResolveClass>

Property Filters

This section contains the following topics:

Equality Filter

Not Equal Filter

Greater Than Filter

Greater Than or Equal to Filter

Less Than Filter

Less Than or Equal to Filter

Wildcard Filter

Any Bits Filter

All Bits Filter

Equality Filter

This example shows an equality filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="fwComputeFirewall">
	<inFilter>
		<eq class="fwComputeFirewall" 
			property="assocState" 
			value="associated" />
	</inFilter>
</configResolveClass>

Not Equal Filter

This example shows a not equal filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="fwComputeFirewall">
	<inFilter>
		<ne class="fwComputeFirewall" 
			property="assocState" 
			value="associated" />
	</inFilter>
</configResolveClass>

Greater Than Filter

This example shows a greater than filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="memoryArray">
	<inFilter>
		<gt class="memoryArray" 
			property="currCapacity" 
			value="1024" />
	</inFilter> 
</configResolveClass>

Greater Than or Equal to Filter

This example shows a greater than or equal to filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="sysdebugCore">
	<inFilter>
		<ge class="sysdebugCore" 
			property="size" 
			value="2097152" />
	</inFilter>
</configResolveClass>

Less Than Filter

This example shows a less than filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="sysdebugCore">
	<inFilter>
		<lt class="sysdebugCore" 
			property="size" 
			value="2097152" />
	</inFilter>
</configResolveClass>

Less Than or Equal to Filter

This example shows a less than or equal to filter::

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="sysdebugCore">
	<inFilter>
		<le class="sysdebugCore" 
			property="size" 
			value="2097152" />
	</inFilter>
</configResolveClass>

Wildcard Filter

This example shows a wildcard filter that finds any virtual firewall whose name begins with the prefix "dmz":

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="fwInstance">
	<inFilter>
		<wcard class="fwInstance" 
			property="name" 
			value="dmz.*" />
	</inFilter>
</configResolveClass>

Any Bits Filter

This example shows an any bits filter:

<configResolveClass 
	cookie="null" 
	inHierarchical="false" 
	classId="extpolClient">
	<inFilter>
		<anybit class="extpolClient" 
			property="capability" 
			value="vm-fw,vm-vasw" />
	</inFilter>
</configResolveClass>

All Bits Filter

This example shows an all bits filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="extpolClient">
	<inFilter>
		<allbits class="extpolClient" 
			property="capability" 
			value="vm-fw,vm-vasw" />
	</inFilter>
</configResolveClass>

Composite Filters

This section contains the following topics:

AND Filter

OR Filter

Between Filter

AND OR NOT Composite Filters

AND Filter

This example shows an and filter that finds firewalls that are associated with a configuration:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="fwComputeFirewall">
	<inFilter>
		<and>
			<eq class="fwComputeFirewall" 
				property="assocState" 
				value="associated" />
			<eq class="fwComputeFirewall" 
				property="configState" 
				value="applied" />
		</and>
	</inFilter>
</configResolveClass>  

OR Filter

This example shows an or filter that returns all managed endpoints whose operational state is either lost-visibility or unregistered.

<configResolveClass 
	inHierarchical="false" 
	cookie="<real_cookie>" 
	classId="extpolClient">
	<inFilter>
		<or>
			<eq class="extpolClient" 
				property="operState" 
				value="unregistered"/>
			<eq class="extpolClient" 
				property="operState" 
				value="lost-visibility"/>
		</or>
	</inFilter>
</configResolveClass>

Between Filter

This example shows a between filter that finds memory arrays with slots 1, 2, 3, 4, or 5 populated:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="memoryarray">
	<inFilter>
		<bw class="memoryArray" 
			property="populated" 
			firstValue="1" 
			secondValue="5"/>
	</inFilter>
</configResolveClass>

AND OR NOT Composite Filters

This example shows an AND OR NOT composite filter that returns all objects of type computeBlade that are located in slots 1 or 8 in all chassis, except for chassis 5:

<configResolveClass 
	inHierarchical="false" 
	cookie="<real_cookie>" 
	classId="computeBlade">
	<inFilter>
		<and>
			<or>
				<eq class="computeBlade" 
					property="slotId" 
					value="1"/>
				<eq class="computeBlade" 
					property="slotId" 
					value="8"/>
			</or>
			<not>
				<eq class="computeBlade" 
					property="chassisId" 
					value="5"/>
			</not>
		</and>
	</inFilter>
</configResolveClass>
 
   

Modifier Filters

NOT Filter

This example shows a not modifier filter:

<configResolveClass 
	cookie="<real_cookie>" 
	inHierarchical="false" 
	classId="extpolClient">
	<inFilter>
		<not>
			<anybit class="extpolClient" 
				property="capability" 
				value="vm-fw" />
		</not>
	</inFilter>
</configResolveClass>

API Examples

This section provides API configuration and management examples.

This section contains the following topics:

Authentication Using the Management Controller

Tenant Management Using the Service Registry

Policy Management

Resource Management

Authentication Using the Management Controller

Access to Cisco 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. We recommend that when activity is completed that the user manually log out of the session using aaaLogout. Use service type mgmt-controller to send login requests to the Cisco VNMC.

This section contains the following topics:

Authentication Request

Authentication Response

Authentication Request

This example shows an authentication request:

POST URL:  https://10.193.33.221/xmlIM/mgmt-controller
XML API payload:
<aaaLogin 
	inName="admin"
	inPassword="Nbv12345"/>

Authentication Response

This examples shows an authentication response:

<aaaLogin 
    cookie="" 
    commCookie="" 
    srcExtSys="0.0.0.0" 
    destExtSys="0.0.0.0" 
    srcSvc="" destSvc="" 
    response="yes" 
    outCookie="<real_cookie>" 
    outRefreshPeriod="600" 
    outPriv="admin,read-only" 
    outDomains="" 
    outChannel="fullssl" 
    outEvtChannel="fullssl" 
    outSessionId="web_13528" 
    outVersion="1.0">
</aaaLogin>

Tenant Management Using the Service Registry

The Service Registry, service type service-reg, creates and manages tenants and the suborganizations that are used to organize the policies and resources. These tenants and suborganizations are arranged in a tree hierarchy for the bottom-up policy and resource resolution. Class names used in tenant and suborganization creation support the following four levels:

Tenant, class orgTenant—Defines the top level organization.

Data Center, class orgDatatcenter—Defines a data center under a Tenant.

Application, class orgApp—Defines an application under a Data Center.

Tier, class orgTier—Defines a tier under an Application.

To create a new organization, or update an existing organization, provide the following:

Object DN

Attribute values

Status equal to created or modified

To delete an organization, use a status = deleted in the request.

This section contains the following topics:

Create or Update Organization Request

Create or Update Organization Response

Create or Update Organization Request

This example shows how to create a tenant named demoTenant.

POST URL:  https://10.193.33.221/xmlIM/service-reg
<configConfMos
	cookie="<real_cookie>">
  <inConfigs>
  	<pair key="org-root/org-demoTenant">
	    <orgTenant dn="org-root/org-demoTenant" 
                             name="demoTenant"
                             status="created"/>
  	</pair>
  </inConfigs>
</configConfMos>

Create or Update Organization Response

This example shows the response that is received after creating a tenant named demoTenant.

<configConfMos
	cookie="<real_cookie>"
	commCookie="2/15/0/839"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="service-reg_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-demoTenant">
			<orgTenant
				descr=""
				dn="org-root/org-demoTenant"
				fltAggr="0"
				level="1"
				name="demoTenant"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

Policy Management


Note In each example where the configConfMos API uses a single XML element <pair> to specify a single configuration object, the configConfMo API can be used as an alternative to obtain the same result.


This section includes the following topics:

Device Policies

Device Profiles

Zone

Object Group

Attribute Dictionary

Policy

PolicySet

Security Profile

Device Policies

This section includes the following topics:

Syslog Policy

SNMP Policy

LogProfile Policy

Syslog Policy

A syslog policy object tracks all actions that take place within the system. It sets the logging level for a device policy and creates mysyslog. Example 2-8 shows a syslog policy request.

Example 2-8 Syslog Policy Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs> 
		<pair key="org-root/syslog-mysyslog">
			<commSyslog dn="org-root/syslog-mysyslog">
			<commSyslogConsole 
				adminState="enabled" 
				severity="emergencies"/>
			<commSyslogClient 
				name="primary" 
				adminState="enabled" 
				hostname="5.6.7.8"
				severity="notifications" 
				forwardingFacility="local7"/>
			<commSyslogClient 
				name="secondary" 
				adminState="enabled"
				hostname="123.23.53.123" 
				severity="warnings" 
				forwardingFacility="local5"/>
			</commSyslog>
		</pair>  
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1b9"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
		<outConfigs>
			<pair key="org-root/syslog-mysyslog">
			<commSyslog   
				adminState="enabled"
				descr=""
				dn="org-root/syslog-mysyslog"
				intId="25301"
				name="mysyslog"   
				port="514"   
				proto="udp"
				severity="warnings"   
				status="created"/>
			</pair>
	</outConfigs>
</configConfMos>

SNMP Policy

This example creates an SNMP policy named mysnmp. Once created, this policy is available by that name in the device profile listing.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/snmp-mysnmp">
		<commSnmp dn="org-root/snmp-mysnmp"
			adminState="enabled"
			descr="The default SNMP policy"
			sysContact="Andrew Jackson"
			sysLocation="San Jose" >
		<commSnmpCommunity 
			community="public" 
			role="read-only"/>
		<commSnmpTrap 
			hostname="nms-1.cisco.com"
			community="private"/>
		<commSnmpTrap 
			hostname="nms-2.cisco.com"
			community="private"/>
		</commSnmp>
		</pair>  
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1bc"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/snmp-mysnmp">
		<commSnmp
			adminState="enabled"
			descr="The default SNMP policy"
			dn="org-root/snmp-mysnmp"
			intId="25281"
			name="mysnmp"
			port="161"
			proto="all"
			sysContact="Andrew Jackson"
			sysLocation="San Jose"/>
		</pair>
	</outConfigs>
</configConfMos>

LogProfile Policy

This example sets the debug level and logging level for a LogProfile policy named debugLog.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/logprof-default">
		<policyLogProfile 
			dn="org-root/logprof-debugLog"
			name="debugLog" 
			level="debug1"
			size="10000000" 
			backupCount="4"/>
		</pair>
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/33"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/logprof-debugLog">
			<policyLogProfile
			adminState="enabled"
			backupCount="4"
			descr="the log level for every process"
			dn="org-root/logprof-debugLog"
			intId="10068"
			level="debug1"
			name="debugLog"
			size="10000000"
			status="modified"/>
		</pair>
	</outConfigs>
</configConfMos>

Device Profiles

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
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/org-Cola/fwdevprofile-myDeviceProfile">
		<fwpolicyFirewallDeviceProfile
			dn="org-root/org-Cola/fwdevprofile-myDeviceProfile"
			adminState="enabled"
			snmpPolicy="mysnmp"
			syslogPolicy="mysyslog"
			timezone="America/Los_Angeles" >
		<commDns 
			name="somedns.com" 
			domain="somedns.com"/>
<!-- 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. -->
		<commDnsProvider 
			hostip="171.70.168.183" 
			order="1"/>
		<commDnsProvider 
			hostip="171.68.226.120" 
			order="2"/>
		<commDnsProvider 
			hostip="64.102.6.247"   
			order="3"/>
		<commNtpProvider 
			name="somentp.com" 
			order="1"/>
		<commNtpProvider 
			name="north-america.pool.ntp.org" 
			order="2"/>
		</fwpolicyFirewallDeviceProfile>
		</pair>
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1ba"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-Cola/fwdevprofile-myDeviceProfile">
		<fwpolicyFirewallDeviceProfile  
			adminState="enabled"  
			coreFilePolicy=""
			descr=""  
			dn="org-root/org-Cola/fwdevprofile-myDeviceProfile"
			dnsPolicy=""  
			enablePolicyDecisionLog="no"
			faultPolicy=""  
			httpPolicy=""  
			httpsPolicy=""  
			intId="25326"
			logProfilePolicy=""  
			name="myDeviceProfile"  
			snmpPolicy="mysnmp"
			status="created"  
			syslogPolicy="mysyslog"  
			telnetPolicy=""
			timezone="America/Los_Angeles"/>
		</pair>
	</outConfigs>
</configConfMos>

Zone

This example creates two zones named trustedClients-0 and trustedServers-0. A set of attributes with values is also assigned.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<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" />
					</policyZoneExpression>
				</policyZoneCondition>
			</policyZone>
		</pair>
		<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" />
					</policyZoneExpression>
				</policyZoneCondition>
			</policyZone>
		</pair>
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1a6"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-tenant0/zone-zone0">
			<policyZone
				descr=""
				dn="org-root/org-tenant0/zone-zone0"
				intId="24295"
				name="zone0"
				status="created"/>
		</pair>
		<pair key="org-root/org-Cisco/zone-trustedServers-0">
			<policyZone
				descr=""
				dn="org-root/org-Cisco/zone-trustedServers-0"
				intId="24404"
				name="trustedServers-0"
				status="created"/>
		</pair>
		<pair key="org-root/org-Cisco/zone-trustedClients-0">
			<policyZone
				descr=""
				dn="org-root/org-Cisco/zone-trustedClients-0"
				intId="24408"
				name="trustedClients-0"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

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
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<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>
			</policyObjectGroup>
		</pair>
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1a4"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-tenant0/objgrp-ftpPorts0">
			<policyObjectGroup
				attributeName=""
				descr=""
				dn="org-root/org-tenant0/objgrp-ftpPorts0"
				intId="24265"
				name="ftpPorts0"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

Attribute Dictionary

This example sets the dictionary that defines the various attribute IDs and names.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
<!-- 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>
		</pair>  
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1a3"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/attr-dict-custom-userAttrs">
			<policyVnspCustomDictionary
				descr=""
				dn="org-root/attr-dict-custom-userAttrs"
				intId="24245"
				name="userAttrs"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

Policy

This example creates a policy named trustedHosts and sets the rules it can use.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<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>
				<policyRuleCondition id="101" order="20">
					<policyNetworkExpression opr="eq">
					<policyNwAttrQualifier attrEp="destination"/>
					<policyZoneNameRef id="1" value="trustedServers-0" />
					</policyNetworkExpression>
				</policyRuleCondition>
				<policyRuleCondition id="103" order="30">
					<policyNetworkExpression opr="eq">
					<policyNwAttrQualifier attrEp="destination"/>
					<policyNetworkPort id="1" placement="0" value="22" />
					</policyNetworkExpression>
				</policyRuleCondition>
				<fwpolicyAction actionType="permit"/>
				</policyRule>
				<policyRule name="allowTacacs" order="2">
				<fwpolicyAction actionType="permit"/>
				</policyRule>
			</policyRuleBasedPolicy>
		</pair>  
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1b5"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-Cisco/pol-trustedHosts">
			<policyRuleBasedPolicy
				descr=""
				dn="org-root/org-Cisco/pol-trustedHosts"
				intId="25131"
				name="trustedHosts"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

PolicySet

This example creates myPolicySet0 and sets the order that policies are applied.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/org-tenant0/pset-myPolicySet0">
			<policyPolicySet 
				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"/>
			</policyPolicySet>
		</pair>
	</inConfigs>
</configConfMos>
 
   

Response

<configConfMos
	cookie="<real_cookied>"
	commCookie="7/15/0/1a8"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-tenant0/pset-myPolicySet0">
			<policyPolicySet
				adminState="enabled"
				descr=""
				dn="org-root/org-tenant0/pset-myPolicySet0"
				intId="24431"
				name="myPolicySet0"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

Security Profile

This example creates a security profile named vnsp-sp1 and assigns the VNSP to it.

Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
cookie="<real_cookie>">
<inConfigs>
<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" />
		</policyVnspAVPair>
		</policyVirtualNetworkServiceProfile>
		</pair>
	</inConfigs>
</configConfMos>

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/15/0/1ac"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-tenant0/vnsp-sp1">
			<policyVirtualNetworkServiceProfile
				descr=""
				dn="org-root/org-tenant0/vnsp-sp1"
				intId="24512"
				name="sp1"
				policySetNameRef="myPolicySet0"
				status="created"
				vnspId="2"/>
		</pair>
	</outConfigs>
</configConfMos>

Resource Management

The Resource Management component performs the following functions:

Assigns the compute firewall to a device policy.

Queries for available firewall instances.

Associates firewall instances with a managed object.

This section includes the following topics:

Compute Firewall

Query Firewall Instances

Associate Firewall Instance

Compute Firewall

This example assigns computeFirewall to a device policy.

Request

POST URL:  https://10.193.33.221/xmlIM/resource-mgr
XML API payload:
<configConfMos 
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/org-Cisco/cfw-VSNaaa">
			<fwComputeFirewall dn="org-root/org-Cisco/cfw-VSNaaa"
				devicePolicy="myDeviceProfile"
				hostname="cfw-VSNaaa"
				dataIpAddress="10.10.10.100">
			</fwComputeFirewall>
		</pair>
	</inConfigs>
</configConfMos> 

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="5/15/0/19a"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes">
	 <outConfigs>
		<pair key="org-root/org-Cisco/cfw-VSNaaa">
			<fwComputeFirewall
				assocState="unassociated"
				configState="not-applied"
				dataIpAddress="10.10.10.100"
				dataIpSubnet="255.255.255.0"
				descr=""
				devicePolicy="myDeviceProfile"
				dn="org-root/org-Cisco/cfw-VSNaaa"
				fltAggr="0"
				hostname="cfw-VSNaaa"
				intId="12368"
				name="VSNaaa"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>

Query Firewall Instances

This example queries all firewall instances and their attributes.

Request

POST URL:  https://10.193.33.221/xmlIM/resource-mgr
XML API payload:
<configResolveClass 
	cookie="<real_cookie>" 
	classId="fwInstance" 
	inHierarchical="false">
	<inFilter>
		<eq class="fwInstance" 
			property="mgmtIp" 
			value="10.193.33.221" />
	</inFilter>
</configResolveClass> 

Response

configResolveClass 
	cookie=<real_cookie>"
	commCookie="5/15/0/1d9"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes"
	classId="fwInstance">
	<outConfigs>
		<fwInstance
			assignedToDn=""
			assoc="none"
			descr=""
			dn="fw/inst-1005"
			fltAggr="0"
			fsmDescr=""
			fsmPrev="DisassociateSuccess"
			fsmProgr="100"
			fsmRmtInvErrCode="none"
			fsmRmtInvErrDescr=""
			fsmRmtInvRslt=""
			fsmStageDescr=""
			fsmStamp="2010-12-03T23:18:13.304"
			fsmStatus="nop"
			fsmTry="0"
			intId="10155"
			mgmtIp="10.193.33.221"
			model=""
			name="firewall"
			pooled="0"
			registeredClientDn="extpol/reg/clients/client-1005"
			revision="0"
			serial=""
			svcId="1005"
			vendor=""/>
	</outConfigs>
</configResolveClass>

Associate Firewall Instance

This example associates a firewall instance to a managed object and assigns firewall-0 to the inst-1005.

Request

POST URL:  https://10.193.33.221/xmlIM/resource-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/org-Cola/cfw-firewall-0">
			<fwComputeFirewall dn="org-root/org-Cola/cfw-firewall-0">
			<fwResourceBinding assignedToDn="fw/inst-1005"/>
			</fwComputeFirewall>
		</pair>
	</inConfigs>
</configConfMos>
 
   

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="5/15/0/1df"
	srcExtSys="10.193.33.221"
	destExtSys="10.193.33.221"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/org-Cola/cfw-firewall-0">
			<fwComputeFirewall
				assocState="associated"
				configState="not-applied"
				dataIpAddress="168.1.1.221"
				dataIpSubnet="255.255.255.0"
				descr=""
				devicePolicy="myDeviceProfile"
				dn="org-root/org-Cola/cfw-firewall-0"
				fltAggr="1"
				hostname="cfw-firewall-0"
				intId="12514"
				name="firewall-0"
				status="modified"/>
		</pair>
	</outConfigs>
</configConfMos>