The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
The following sections identify common VNMC API methods, describe API conventions, and provide example requests and responses:
The following topics describe the methods and filters that VNMC uses:
•Query Methods for Information Gathering
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:
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.
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>"/>
Example 2-4 shows the method for logging out of a session.
Example 2-4 Logging Out of a Session
<aaaLogout
inCookie="<real_cookie>"/>
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 obtain information that includes hierarchy, state, and scope.
The following sections describe available query methods:
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.
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.
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.
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.
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.
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.
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.
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.
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>
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>
Use filters to create specific and targeted queries, as described in the following topics:
Simple filters use true and false conditions, as described in the following topics:
In addition to inHierarchical (shown in the following examples), inRecursive and inSingleLevel can also be set to true or false.
The following example shows a simple filter using a false condition:
<configResolveClass
cookie="<real_cookie>"
classId="topSystem"
inHierarchical="false">
<inFilter>
</inFilter>
</configResolveClass>
The following example shows a simple filter using a true condition:
<configResolveClass
cookie="<real_cookie>"
classId="topSystem"
inHierarchical="true">
<inFilter>
</inFilter>
</configResolveClass>
The following sections describe how to use property filters:
•Greater Than or Equal to 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>
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>
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>
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>
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>
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>
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>
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>
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>
The following topics describe composite filters:
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>
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>
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>
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>
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>
The following sections provide API configuration and management examples:
•Authentication Using the Management Controller
•Tenant Management Using the Service Registry
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.
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:
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"/>
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>
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
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>
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>
The following topics describe how to manage policies:
•Zone
The following topics provide examples for working with device policies:
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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:
•Assign a Device Profile to a Compute 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>
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>
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>
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>