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

Common API Methods and Conventions

Table Of Contents

Common API Methods and Conventions

Methods and Filters

Authentication Methods

Login

Refreshing the Session

Logging Out of the Session

Response to a Failed Login

Query Methods for Information Gathering

configResolveDn

configResolveDns

configResolveClass

configResolveClasses

configFindDnsByClassId

configResolveChildren

configResolveParent

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

Compute Security Profile

Resource Management

Create an Edge Firewall

Create a Compute Firewall

Assign a Device Profile to a Compute Firewall

Query Firewall Instances


Common API Methods and Conventions


The following sections identify common VNMC API methods, describe API conventions, and provide example requests and responses:

Methods and Filters

API Examples

Methods and Filters

The following topics describe the methods and filters that VNMC uses:

Authentication Methods

Query Methods for Information Gathering

Query Methods for Policies

Query Methods for Faults

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.


The following topics describe authentication methods in more detail:

Login

Refreshing the Session

Logging Out of the Session

Response to a Failed Login

Login

Example 2-1 shows a login request using HTTPS to connect to VNMC, and a Linux POST command to post authentication requests.

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="Company@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, 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.

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 The VNMC event channel uses HTTP, so it is neither encrypted nor 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 shows 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 shows 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 shows the response to a failed login.

Example 2-5 Response 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.

The following sections describe available query methods:

configResolveDn

configResolveDns

configResolveClass

configResolveClasses

configFindDnsByClassId

configResolveChildren

configResolveParent

configScope

configResolveDn

When using configResolveDn, note the following:

The object specified by the DN is 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.

See the example request/response in configResolveDn.

configResolveDns

When using configResolveDns to resolve multiple DNs, note 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.

configResolveClass

When using configResolveClass to resolve a class, note 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 get all instances of equipment, query the equipmentItem class. To obtain only a list of servers, use computeBlade as the attribute value for classId in the query.

See the example request/response in configResolveClass.

configResolveClasses

When using configResolveClasses to resolve multiple classes, note 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 inIds attribute, an XML parsing error is generated. The query cannot execute.


See the example request/response in configResolveClasses.

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.

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.

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.

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 simultaneously is resource intensive. Instead, identify the type of policy and the parent organization to which the policies are attached.

Example 2-6 shows a query for rule-based policies.

Example 2-6 Example Query 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, as follows:

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

Query Methods for Faults

Example 2-7 shows a query for faults.

Example 2-7 Example Query for Faults

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

The following 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, as described in the following topics:

Simple Filters

Property Filters

Composite Filters

Modifier Filters

Simple Filters

Simple filters use true and false conditions, as described in the following topics:

False Conditions

True Conditions

In addition to inHierarchical (shown in the following examples), inRecursive and inSingleLevel can also be set to true or false.

False Conditions

The following example shows a simple filter using a false condition:

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

True Conditions

The following example shows a simple filter using a true condition:

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

Property Filters

The following sections describe how to use property filters:

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

The following 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

The following 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

The following example shows a greater than filter:

<configResolveClass
	cookie="<real_cookie>"
	classId="eventRecord"
	inHierarchical="false">
	<inFilter>
		<gt class="eventRecord"
			property="txId"
			value="36520" />
	</inFilter>
</configResolveClass>
 
   

Greater Than or Equal to Filter

The following 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

The following 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

The following 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

The following 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

The following 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

The following 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

The following topics describe composite filters:

And Filter

Or Filter

Between Filter

And Or Not Composite Filters

And Filter

The following 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

The following 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

The following example shows a between filter:

<configResolveClass
	cookie="<real_cookie>"
	classId="eventRecord"
	inHierarchical="false">
	<inFilter>
		<bw class="eventRecord"
			property="txId"
			firstValue="4"
			secondValue="5"/>
	</inFilter>
</configResolveClass>
 
   

And Or Not Composite Filters

The following example shows an and or not composite filter that returns all objects of type fwComputeFirewall that have an associated state of unassociated or a config state of not-applied, but that do not have an auxiliary property value of reachability:

<configScope 
	cookie="<real_cookie>" 
	dn="org-root" 
	inClass="fwComputeFirewall" 
	inHierarchical="false" 
	inRecursive="false">
	<inFilter>
		<and>
			<or>
				<eq class="fwComputeFirewall" property="assocState" value="unassociated" />
				<eq class="fwComputeFirewall" property="configState" value="not-applied" />
			</or>
			<not>
				<eq class="fwComputeFirewall" property="auxProps" value="reachability"/>
			</not>
		</and>
	</inFilter>
</configScope>
 
   

Modifier Filters

Not Filter

The following 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

The following sections provide API configuration and management examples:

Authentication Using the Management Controller

Tenant Management Using the Service Registry

Policy Management

Resource Management

The following sections demonstrate how configConfMos is used to create, modify, or delete an MO (or object). In each example where the configConfMos API uses a single XML element <pair> to specify a single configuration object, you can use the configConfMo API to obtain the same result.

Authentication Using the Management Controller

Access to 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, 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 VNMC.

The following topics provide examples of authentication requests and responses:

Authentication Request

Authentication Response

Authentication Request

The following 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

The following example 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 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 orgDatacenter—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 information:

Object DN

Attribute values

Status equal to created or modified

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

The following topics provide examples of create or update requests and responses:

Create or Update Organization Request

Create or Update Organization Response

Create or Update Organization Request

The following example shows how to create a tenant named demoTenant:

<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

The following 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

The following topics describe how to manage policies:

Device Policies

Device Profiles

Zone

Object Group

Attribute Dictionary

Policy

PolicySet

Compute Security Profile

Device Policies

The following topics provide examples for working with device policies:

Syslog Policy

SNMP Policy

LogProfile Policy

Syslog Policy

A syslog policy object tracks all actions that take place within the system and sets the logging level for a device profile. The following example creates a syslog policy named mysyslog.

Request

<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

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

Request

<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-23.host123.com"
			community="private"/>
		<commSnmpTrap 
			hostname="nms-42.host123.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

The following 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-debugLog">
		<policyLogProfile
			dn="org-root/logprof-debugLog"
			name="debugLog"
			level="debug1"
			size="10000000"
			backupCount="4"/>
		</pair>
	</inConfigs>
</configConfMos>
 
   

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/12/0/17d0"
	srcExtSys="172.20.101.150"
	destExtSys="172.20.101.150"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/logprof-debugLog">
			<policyLogProfile
			adminState="enabled"
			backupCount="4"
			descr=""
			dn="org-root/logprof-debugLog"
			intId="10514"
			level="debug1"
			name="debugLog"
			size="10000000"
			status="created"/>
		</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"
			snmpPolicy="mysnmp"
			syslogPolicy="mysyslog"
			timezone="America/Los_Angeles" >
		<commDns 
			name="somedns.com" 
			domain="somedns.com"/>
<!-- The order attribute 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  
			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

The following example creates two zones: trustedClients-0 and trustedServers-0. A set of attributes with values is also assigned.


Note In the VNMC UI, a zone is represented as a vZone (virtual Zone).


Request

POST URL:  https://10.193.33.221/xmlIM/policy-mgr
XML API payload:
<configConfMos
	cookie="<real_cookie>">
	<inConfigs>
		<pair key="org-root/org-tenant1/zone-trustedClients-0">
<!-- Create a zone of all VMs in the 192.168.1.0/24 subnet -->
			<policyZone dn="org-root/org-tenant1/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-tenant1/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-tenant1/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-tenant1/zone-trustedServers-0">
			<policyZone
				descr=""
				dn="org-root/org-tenant1/zone-trustedServers-0"
				intId="24404"
				name="trustedServers-0"
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant1/zone-trustedClients-0">
			<policyZone
				descr=""
				dn="org-root/org-tenant1/zone-trustedClients-0"
				intId="24408"
				name="trustedClients-0"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>
 
   

Object Group

The following 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

The following example creates a 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-tenant1 -->
		<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

Beginning with version 2.0, VNMC no longer uses the adminState property for ACL policies because VSG compute firewalls do not support a value of disabled for this property; the default value is enabled. However, VNMC continues to use the adminState property in other types of policies, such as those used by ASA 1000V.

If you set the adminState property via the API for an ACL policy, the response will contain the following error message:

<configConfMos
	cookie="<real_cookie>"
	commCookie="7/12/0/55"
	srcExtSys="10.193.76.15"
	destExtSys="10.193.76.15"
	srcSvc="sam_extXMLApi"
	destSvc="policy-mgr_dme"
	response="yes"
	errorCode="170"
	invocationResult="unidentified-fail"
	errorDescr="Admin implicit props cannot be modified, prop=adminState>
 
   

The following 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-tenant1/pol-trustedHosts">
			<policyRuleBasedPolicy dn="org-root/org-tenant1/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-tenant1/pol-trustedHosts">
			<policyRuleBasedPolicy
				descr=""
				dn="org-root/org-tenant1/pol-trustedHosts"
				intId="25131"
				name="trustedHosts"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>
 
   

PolicySet

The following example creates ACL-PolicySet and sets the order in which policies are applied.

Request

<configConfMos
	cookie="<real_cookie>"
	inHierarchical="false">
	<inConfigs>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test">
			<policyPolicyNameRef 
				dn="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test"
				order="100" 
				policyName="Test" 
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet">
			<policyPolicySet 
				descr="" 
				dn="org-root/org-tenant1/pset-ACL-PolicySet"
				name="ACL-PolicySet"
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant/pset-ACL-PolicySet/polref-Test-03">
			<policyPolicyNameRef 
				dn="org-root/org-tenant/pset-ACL-PolicySet/polref-Test-03"
				order="300" 
				policyName="Test-03" 
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-02">
			<policyPolicyNameRef
				dn="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-02"
				order="200" 
				policyName="Test-02" 
				status="created"/>
		</pair>
	</inConfigs>
</configConfMos>

Response

<configConfMos 
	cookie="<real_cookie>" 
	commCookie="7/12/0/187c" 
	srcExtSys="172.20.101.150" 
	destExtSys="172.20.101.150" 
	srcSvc="sam_extXMLApi" 
	destSvc="policy-mgr_dme" 
	response="yes">
	<outConfigs>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet">
			<policyPolicySet 
				adminState="enabled" 
				descr="" dn="org-root/org-tenant1/pset-ACL-PolicySet" 
				intId="10666" 
				name="ACL-PolicySet" 
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test">
			<policyPolicyNameRef
				dn="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test" 
				order="100"
				policyName="Test"
				status="created"/>
		</pair>
		<pair key="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-02">
			<policyPolicyNameRef 
				dn="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-02"
				order="200" 
				policyName="Test-02"
				status="created"/>
		</pair>
			<pair key="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-03">
				<policyPolicyNameRef
					dn="org-root/org-tenant1/pset-ACL-PolicySet/polref-Test-03" 
					order="300" 
					policyName="Test-03" 
					status="created"/>
		</pair>
	</outConfigs>
</configConfMos>
 
   

Compute Security Profile

The following 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:

Creates an edge firewall.

Assigns compute and edge firewalls to policies.

Queries for available firewall instances.

Associates firewall instances with a managed object.

Allows the binding of organizations to resource pools.

Interacts with virtual centers to retrieve VM attributes.

The following topics provide examples for working with firewalls:

Create an Edge Firewall

Create a Compute Firewall

Assign a Device Profile to a Compute Firewall

Query Firewall Instances

Create an Edge Firewall

The following example creates an edge firewall with one inside data interface and one outside data interface.

Request

<configConfMos
	cookie="<real_cookie">
	<inConfigs>
		<pair key="org-root/efw-default"> 
			<fwEdgeFirewall 
				dn="org-root/efw-default"
				rn="efw-default" 
				name="default" 
				haMode="standalone" 
				status="created"/> 
		</pair>  
		<pair key="org-root/efw-default/interface-inside">
			<fwDataInterface 
				dn="org-root/efw-default/interface-inside"
				name="inside" 
				role="inside"  
				ipSubnet="255.255.255.0"  
				ipAddressPrimary="10.10.10.1"
				status="created"/>
		</pair>
		<pair key="org-root/efw-default/interface-outside">
			<fwDataInterface 
				dn="org-root/efw-default/interface-outside"
				name="outside" 
				role="outside"
				ipSubnet="255.255.255.0"  
				ipAddressPrimary="10.10.20.1"
				status="created"/>
		</pair>
	</inConfigs>
</configConfMos> 
 
   

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="5/12/0/35da"
	srcExtSys="172.20.101.150"
	destExtSys="172.20.101.150"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes">
		<outConfigs>
			<pair key="org-root/efw-default">
				<fwEdgeFirewall
					assocState="unassociated"
					auxProps=""
					configState="not-applied"
					descr=""
					dn="org-root/efw-default"
					fltAggr="0"
					haMode="standalone"
					hostname="edge-firewall"
					intId="10467"
					name="default"
					status="created"/>
			</pair>
			<pair key="org-root/efw-default/interface-inside">
				<fwDataInterface
					descr=""
					dn="org-root/efw-default/interface-inside"
					intId="10468"
					ipAddressPrimary="10.10.10.1"
					ipAddressSecondary="0.0.0.0"
					ipSubnet="255.255.255.0"
					isIpViaDHCP="no"
					name="inside"
					role="inside"
					status="created"/>
			</pair>
			<pair key="org-root/efw-default/interface-outside">
				<fwDataInterface
					descr=""
					dn="org-root/efw-default/interface-outside"
					intId="10469"
					ipAddressPrimary="10.10.20.1"
					ipAddressSecondary="0.0.0.0"
					ipSubnet="255.255.255.0"
					isIpViaDHCP="no"
					name="outside"
					role="outside"
					status="created"/>
			</pair>
	</outConfigs>
</configConfMos>
 
   

Create a Compute Firewall

The following example creates a compute firewall with the name test5.

Request

<configConfMos 
	cookie="<real_cookie>" 
	inHierarchical="false">
	<inConfigs>
		<pair key="org-root/cfw-test5">
			<fwComputeFirewall 
				dn="org-root/cfw-test5"
				name="test5"
				dataIpAddress="5.5.5.5" 
				dataIpSubnet="255.255.255.0" 
				status="created"/>
		</pair>
	</inConfigs>
</configConfMos>
 
   

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="5/12/0/1545"
	srcExtSys="172.25.97.246"
	destExtSys="172.25.97.246"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/cfw-test5">
			<fwComputeFirewall
				assocState="unassociated"
				auxProps=""
				configState="not-applied"
				dataIpAddress="5.5.5.5"
				dataIpSubnet="255.255.255.0"
				descr=""
				devicePolicy=""
				dn="org-root/cfw-test5"
				fltAggr="0"
				hostname="firewall"
				intId="10583"
				name="test5"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>
 
   

Assign a Device Profile to a Compute Firewall

Beginning with VNMC 2.0, fw:ComputeFirewall.devicePolicy is deprecated and should not be modified via the XML API. Instead, create a child MO of type logical:DeviceProfileAssociation, and set logical:DeviceProfileAssociation.profileRef. The logical:DeviceProfileAssociation should be a child of fw:ComputeFirewall.

If you modify fw:ComputeFirewall.devicePolicy, you might see inconsistent behavior between fw:ComputeFirewall.devicePolicy and logical:DeviceProfileAssociation, and thus what is displayed in the UI.

The following example assigns the device profile my-profile-ref to the compute firewall test5, which was created in Create a Compute Firewall.

Request

<configConfMos 
	cookie="<real_cookie>" 
	inHierarchical="false">
	<inConfigs>
		<pair key="org-root/cfw-test5/device-profile">
			<logicalDeviceProfileAssociation 
				dn="org-root/cfw-test5/device-profile"
				profileRef="my-profile-ref" 
				status="created"/>
		</pair>
	</inConfigs>
</configConfMos>
 
   

Response

<configConfMos
	cookie="<real_cookie>"
	commCookie="5/12/0/1571"
	srcExtSys="172.25.97.246"
	destExtSys="172.25.97.246"
	srcSvc="sam_extXMLApi"
	destSvc="resource-mgr_dme"
	response="yes">
	<outConfigs>
		<pair key="org-root/cfw-test5/device-profile">
			<logicalDeviceProfileAssociation
				descr=""
				dn="org-root/cfw-test5/device-profile"
				intId="10586"
				name=""
				profileRef="my-profile-ref"
				status="created"/>
		</pair>
	</outConfigs>
</configConfMos>
 
   

Query Firewall Instances

The following example queries all firewall instances with the management IP address of 10.193.33.221 and obtains 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>