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 provide general information about Cisco Virtual Network Management Center (VNMC) and the XML application programming interface (API):
•Overview of VNMC and XML APIs
•Capturing XML Interchange Between the VNMC GUI and Server
The following sections provide an overview of VNMC and the XML API:
•VNMC
•VNMC Management Information Model
VNMC is a virtual appliance that provides centralized device and security policy management for Cisco virtual services. Designed to support enterprise and multiple-tenant cloud deployments, VNMC provides transparent, seamless, and scalable management for securing virtualized data center and cloud environments.
With a built-in GUI and an XML API, VNMC enables you to configure, deploy, and manage virtual services throughout the data center from a central location.
VNMC is built on an information model-driven architecture in which each managed device is represented by its subcomponents (or objects), which are parametrically defined. This model-centric approach provides a flexible and simple mechanism for securing a virtualized infrastructure with compute and edge firewalls.
VNMC supports multiple client organizations, or tenants, that have their own virtualized compute, network, and storage resources, and that are deployed across a shared physical infrastructure. Multiple tenants can coexist on the same infrastructure, with each tenant maintaining administrative privileges for its virtualized resources. This multiple-tenancy design enables you to meet the specified service level agreement (SLA) for each tenant, including compute, network, storage, and security policies.
All physical and logical components that comprise a VNMC service component are represented in a hierarchical management information model. This model is referred to as the management information tree. The hierarchical structure starts at the top and contains parent and child nodes. Each node in the tree represents a managed object (or group of objects) and displays the object's administrative and operational states. Each object has a unique distinguished name (DN) that describes the object and its location in the tree.
Managed objects are abstractions of VNMC-managed entities, such as policies, rules, security profiles, and compute and edge firewalls. By invoking the API, objects are read from and written to the management information tree. The information model of an individual VNMC service component is centrally stored and managed by the data management engine (DME). When a user initiates an administrative change to a VNMC service component (for example, by associating an edge firewall profile to an ASA 1000V, the DME first applies that change to the information model, and later the change is applied to the actual ASA 1000V. This approach is called a model-driven framework.
VNMC consists of multiple service components that provide modularized functions for management, tenant management, policy management, resource management, and so on. These components are also called service providers or applications. Each component is accessed through a unique URL.
The following sections describe the VNMC components:
Each component has its own data model and a DME that processes the model-driven service requests. Each component maintains its own management information tree storage (both in memory and in the persistent storage). Data sharing across different service components is achieved with ad-hoc interservice API communications or by using a publish or subscribe method.
Management Controller, also known as the core service, provides system-related services for the VNMC virtual machine, such as:
•Authenticates and authorizes user logins in local or LDAP mode.
•Provides access control, such as locales, roles, and trusted points.
•Maintains system information, such as the IP address, subnet mask, gateway, and hostname.
•Upon user input, performs system maintenance operations, such as database backup, data export, and data import.
•Maintains system diagnostic information, such as audit logs, faults, event logs, and core dump files.
The Management Controller type is mgmt-controller. Use this service type in the API URL for all requests related to the Management Controller.
Service Registry is the central service repository that holds information about all registered managed endpoints (such as ASA 1000Vs or VSGs) and the service providers (such as Policy Manager or Resource Manager).
Note Service endpoints are referred as clients in the GUI.
Service endpoints and the service providers register themselves dynamically with the Service Registry and retrieve information about service components from the Service Registry. The Service Registry is also responsible for tenant management and provides the following services:
•Upon user input, creates, deletes, and updates organizations (tenants, data centers, applications, and tiers). Organization changes are automatically propagated to Policy Manager and Resource Manager when policies and resources are attached to the intended organizations.
•Maintains information about the registered services (such as providers, endpoints, and Management Controller).
•Maintains diagnostic information, such as audit logs, faults, and event logs.
The Service Registry type is service-reg. Use this service type in the API URL for all requests related to the Service Registry.
Resource Manager manages logical compute and edge firewalls and their association with VSGs and ASA 1000Vs, respectively. When an edge firewall is associated with an ASA 1000V, the device configuration profile information (defined by the edge firewall) is pushed to the ASA 1000V which, in turn, triggers the ASA 1000V to download the security profiles and policies from Policy Manager.
Resource Manager is responsible for the following services:
•Maintains an inventory of ASA 1000Vs, VSGs, and Cisco Virtual Supervisor Modules (VSMs).
•With user input, defines compute firewalls and associates them with VSGs for provisioning.
•With user input, defines edge firewalls and associates them with ASA 1000Vs for provisioning.
•Interacts with VMware vCenter instances to retrieve Virtual Machine (VM) attributes.
•Maintains an inventory of discovered VMs and distributes them to the VSGs with the following information:
–VM attributes, such as name, hypervisor, parent vApp, and cluster
–vNIC attributes, such as port profile name and IP address
•Manages pools of VSGs and ASA 1000Vs.
•Maintains health states and faults for VSGs and ASA 1000Vs.
•Maintains diagnostic information, such as audit logs, faults, and event logs.
The Resource Manager type is resource-mgr. Use this service type in the API URL for all requests related to Resource Manager.
Policy Manager is the central repository for device configuration profiles, service policies, service profiles, and all associated artifacts. When a compute firewall is associated with a VSG from Resource Manager, the VSG queries Policy Manager to resolve the device profile, service profiles, and all referenced policies. The VSG then configures itself according to the information retrieved from Policy Manager. The same process is used when an edge firewall is associated with an ASA 1000V.
Policy Manager provides the following services:
•Using the user input, defines:
–Firewall device profiles
–Object groups
–Policies
–Policy rules with conditions on:
—Network attributes such as protocol, source or destination, IP address, and port.
—VM attributes such as instance name, guest OS, zone, parent application, port profile, cluster, resource pool, hostname, and hypervisor.
—Custom attributes.
–Policy sets
–Security profile dictionary and custom attributes
–Service profiles
–VNMC system management device profiles and policies for NTP, DNS, syslog, and faults.
–Virtual zones (vZones)
•Using the user input, assigns policies and policy sets.
•Distributes service policies, service profiles, device profiles, and associated objects to edge and compute firewall instances.
•Maintains diagnostic information such as audit logs, faults, and event logs.
The Policy Manager service type is policy-mgr. Use this service type in the API URL for all requests related to Policy Manager.
VM Manager is responsible for interacting with VMware vCenter and maintaining the VM information retrieved from vCenter. It is a backend service without any user-accessible services. The VM Manager service type is vm-mgr.
The VNMC XML API is a programmatic way of integrating and interacting with VNMC. The API interface accepts XML documents by using the HTTPS protocol. Developers can use any programming language to generate XML documents that contain the API methods. Configuration and state information is stored in a hierarchical tree structure known as the management information tree, and is completely exposed through the XML API.
The API model is recursively driven and provides major functionality for application development. For example, changes can be made on a single object, an object subtree, or the entire object tree. Changes can be made to a single attribute on an object or applied to the entire VNMC structure with a single API call.
The API operates in forgiving mode. Missing attributes are substituted with default values (if applicable) that are maintained in the DME. If multiple managed objects (such as policies) are being configured, and any of the managed objects cannot be configured, the API stops the operation, returns the configuration to its prior state, and then stops the API process with a fault notification.
The API leverages an asynchronous operations model to improve scalability and performance. Processes that require time to complete are nonblocking or asynchronous; that is, faster API processes are not blocked or delayed by those that require more time. A process receives a success message upon a valid request and a completion message when the task is finished.
Full event subscription is supported. VNMC sends notifications to all subscribers for the events that occur (such as changes to managed objects), and indicates the type of state change.
Future updates to the managed object data model will conform to the existing object model to ensure backward compatibility. If existing properties are changed during a product upgrade, it will be handled during the database load after the upgrade. New properties will be assigned default values.
VNMC uses a model-driven architecture, where changes are first applied to logical constructs in the form of managed objects. The managed objects then apply the changes to the endpoints to achieve the required state (that is, configuration) of the endpoint.
Operation of the API is transactional and terminates on a single data model. VNMC is responsible for all endpoint (ASA 1000V, VSG, and VSM) communication (such as state updates). API users cannot communicate directly with endpoints, which relieves the users from administering isolated, individual component configurations.
The VNMC API model includes the following programmatic entities:
•Classes—Objects and their properties and states in the management information tree.
•Methods—Actions that the API performs on one or more objects.
•Types—Collections or ranges of allowed values for object properties.
A typical request comes into a service component's DME and is placed in the transactor queue in first-in, first-out (FIFO) order. The transactor gets the request from the queue, interprets the request, and performs an authorization check. When the request is confirmed, the transactor updates the management information tree. This process is done in a single transaction.
The data model HTML documents and schemas for all VNMC service providers are packaged with the VNMC server and can be accessed from either of the following URLs:
•https://vnmc-ip-address/doc, which includes:
–core
–policy-mgr
–resource-mgr
–service-reg
•https://vnmc-ip-address/schema, which includes:
–core.in.xsd—Management controller configuration APIs and data model.
–core.out.xsd—Management controller query APIs and data model.
–policy-mgr.in.xsd—Policy manager configuration APIs and data model.
–policy-mgr.out.xsd—Policy manager query APIs and data model.
–resource-mgr.in.xsd—Resource manager configuration APIs and data model.
–resource-mgr.out.xsd—Resource manager query APIs and data model.
–service-reg.in.xsd—Service registry configuration APIs and data model.
–service-reg.out.xsd—Service registry query APIs and data model.
You can access VNMC services using XML API requests over HTTPS protocol. The HTTPS request URL format is:
https://vnmc-ip-address/xmlIM/service-type
where service-type is the service type of the intended service provider as described in VNMC Components. For example, to submit a request to the Policy Manager, use the service type policy-mgr as shown in the following example:
https://vnmc-ip-address/xmlIM/policy-mgr
You can identify a specific object by its distinguished name (DN) or by its relative name (RN) as described in the following sections:
A DN enables you to unambiguously identify a target object. DNs use the following format, which consists of a series of relative names:
dn = rn/rn/rn/rn...
For example, a series of relative names might resemble the following example:
org-root/org-tenant1/zone-trustedServers-0
In the following example, the DN provides a fully qualified path for a Zone (vZone in the GUI) object (zone-trustedServers-0) from the top of the object tree to the object. The DN specifies the exact managed object on which the API call is operating.
< ...dn = "org-root/org-tenant1/zone-trustedServers-0" />
An RN identifies an object within the context of its parent object. The DN of an object consists of the parent DN and the RN in the following format:
dn = parent-dn/rn
For example, a Zone (vZone in the GUI) object with the name trustedServers-0 that resides under the tenant Tenant1 has the following related RN and DNs:
•The object's RN is zone-trustedServers-0.
•The object's parent tenant DN is org-root/org-Tenant1.
•The object's DN is org-root/org-Tenant1/zone-trustedServers-0.
Four method categories are used to interact with VNMC. Each API is a method, and each method corresponds to an XML document. The following sections describe method categories in more detail and how to use query filters to retrieve the required information:
Note Several code examples in this guide substitute the term <real_cookie> for an actual cookie such as 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf. The VNMC cookie is a 47-character string. It is not the type of cookie that web browsers store locally to maintain session information.
Authentication methods initiate and maintain active VNMC sessions. A successful authentication must be performed before other API calls are allowed. API requests are cookie authenticated.
After a connection session is established and authenticated, a cookie is returned in the response. It is valid for 7200 seconds (120 minutes). The cookie must be refreshed during the session period to prevent it from expiring. Each refresh operation creates a cookie valid for the default interval.
A maximum of 256 sessions to VNMC can be opened at any one time. Subsequent login requests are rejected after the maximum session limit is reached.
Operations are performed by using the HTTP POST method. VNMC supports only the HTTPS protocol on port 443. The HTTP envelope contains the XML configuration.
Table 1-1 describes the available authentication methods.
Query methods obtain information on the current configuration state of a VNMC object.
Most query methods have the argument inHierarchical, with a Boolean value of true/yes or false/no. If true, the inHierarchical argument returns all child objects. For example:
<configResolveDn ... inHierarchical="false"></>
<configResolveDn ... inHierarchical="true"></>
API query methods can also include an inRecursive argument that specifies whether or not the call should be recursive; that is, whether the call should follow objects that point back to the referring objects or to the parent object.
Table 1-2 describes the available query methods.
The API includes filters that increase the usefulness of the query methods. These filters can be passed as part of a query and are used to identify the wanted result set. The following sections describe the available filters:
There are two simple filters: true and false. These filters react to the simple states of true or false, as follows:
•True filter—Result set objects carry the Boolean condition of true.
•False filter—Result set objects carry the Boolean condition of false.
For more information, see Simple Filters.
Property filters use object property values as the criteria for inclusion in a result set. To create most property filters, the classId and propertyId of the target object and property are required, along with a value for comparison.
Table 1-3 describes the types of property filters.
For more information, see Property Filters.
Composite filters are composed of two or more component filters and thereby enable greater flexibility in creating result sets. For example, a composite filter could restrict the result set to only those objects that were accepted by at least one of the contained filters.
Table 1-4 describes the available composite filters.
For more information, see Composite Filters.
Modifier filters change the results of a contained filter. Only the NOT modifer filter is supported. This filter negates the result of a contained filter. Use this filter to obtain objects that do not match contained criteria.
For more information, see Modifier Filters.
Several methods enable you to make configuration changes to managed objects. Depending on the configuration method you use, the changes can be applied to the whole tree, a subtree, or an individual object. Examples of configuration methods include the following:
•configConfMo—Affects a single subtree, that is, a DN.
•configConfMos—Affects multiple subtrees, that is, several DNs.
•configConfMoGroup—Makes the same configuration changes to multiple subtree structures or managed objects.
Most configuration methods use the argument inHierarchical. These values do not play a significant role during configuration because child objects are included in the XML document and the DME operates in the forgiving mode.
VNMC validates all configuration information that is entered via the API for each property, including the data type (such as integer, boolean, or string) and any additional constraints (such as an integer range or string regular expression). If the information supplied via the API does not meet the requirements for the specified property, VNMC stops the transaction and issues a failure response.
For more information about failure responses, see Success or Failure Responses.
When an object is created, changed, or deleted because of a user- or system-initiated action, an event is generated. Applications can receive VNMC state change information by regular polling or subscribing to events. Because polling is resource-expensive, event subscription is the preferred method of notification.
Event subscription allows a client application to register for event notification from VNMC. When an event occurs, VNMC sends a notification of the event and its type to the subscribing client applications. Only actual change events are sent, not the object's unaffected attributes. This process applies to all object changes in the system.
To subscribe to event notification:
Step 1 Log into VNMC to obtain a valid cookie for event subscription. If you are not logged in, the event subscription request will be rejected with an error response.
Step 2 Open an HTTP session and keep the session open.
Step 3 Post the eventSubcribe request through the HTTP session as follows:
<eventSubscribe cookie="<real_cookie>"></eventSubscribe>
After the eventSubscribe request is accepted by VNMC, VNMC will send all new events as they occur through the HTTP session.
Each event has a unique event identifier (ID). Event IDs operate as counters and are included in all event notifications. When an event is generated, the event ID counter increments and a new event is assigned a new event ID. This process enables tracking of events and ensures that no event is missed. If an event is missed by the client, you can use loggingSyncOcns to retrieve the missed event.
Note For VNMC, only the HTTP protocol is supported for event subscription. Use HTTP when posting the event subscription request.
The asynchronous event notifications for the following methods do not use the same format as other methods. Instead, event notifications for these methods use the format and syntax shown in the examples.
•configMoChangeEvent
<xs:element name="configMoChangeEvent" type="configMoChangeEvent" substitutionGroup="externalMethod"/>
<xs:complexType name="configMoChangeEvent" mixed="true">
<xs:attribute name="cookie" type="xs:string"/>
<xs:attribute name="response" type="YesOrNo"/>
<xs:attribute name="errorCode" type="xs:unsignedInt"/>
<xs:attribute name="errorDescr" type="xs:string"/>
<xs:attribute name="invocationResult" type="xs:string"/>
</xs:complexType>
•methodVessel
<xs:element name="methodVessel" type="methodVessel" substitutionGroup="externalMethod"/>
<xs:complexType name="methodVessel" mixed="true">
<xs:attribute name="cookie" type="xs:string"/>
<xs:attribute name="response" type="YesOrNo"/>
<xs:attribute name="errorCode" type="xs:unsignedInt"/>
<xs:attribute name="errorDescr" type="xs:string"/>
<xs:attribute name="invocationResult" type="xs:string"/>
</xs:complexType>
Unified Modeling Language (UML) diagrams complement the object-oriented development approach used for VNMC. These diagrams display classes and associations between classes, along with attributes and methods, so that you can gain an overall view of VNMC classes and how the classes relate to one another.
The VNMC UML diagrams include the following attributes, as described in the subsequent topics:
•Aggregations and Compositions
To view sample VNMC UML diagrams, see "UML Diagrams."
In UML, a class is a representation of an object. In VNMC, examples of objects, and therefore classes, are tenants, compute firewalls, edge firewalls, policies, and profiles. In general, anything that you can create in VNMC can be considered a class.
Classes are the primary components of UML and are presented as rectangles in UML diagrams, as shown in Figure 1-1.
Figure 1-1 Representation of a Class in UML
The class representation contains the following three sections:
•Class name—Name of the object.
•Attribute—Information that is stored about the object.
•Method—Operations that the object or class can perform.
Figure 1-2 shows an example of a class with example entries in each section.
Figure 1-2 Example Class in UML
Not all class diagrams contain content in all sections. For example, you might see UML class diagrams with class name and attributes, but without methods. In these situations, the three sections are displayed, but the method section contains no information.
An association in UML diagrams indicates that a link or dependency exists between two or more classes. Associations are represented in a number of ways, as shown in Figure 1-3 and described in Table 1-5.
Figure 1-3 Associations in a UML Diagram
Similar or closely related classes often use many of the same attributes or methods. To prevent repetitive coding for multiple classes, UML employs an inheritance mechanism that enables you to reuse existing attributes and methods.
In an inheritance situation, the class that inherits the information is referred to as the subclass, and the class that is inherited from is referred to as the superclass. If all attributes and methods of one class are inherited by another class, that situation is referred to as pure inheritance.
In UML diagrams, inheritance is indicated by solid line with a closed arrowhead pointing from the subclass to the superclass.
Aggregations and compositions are types of associations that have unique characteristics. When working with UML diagrams, it is important to understand the differences between aggregations and compositions, and how they are presented in the diagrams.
Table 1-6 describes the differences between aggregation and composition associations.
The VNMC GUI is a web-based application that is developed using an Adobe Flex GUI framework. As a result, you can capture the XML interchange between the GUI and the VNMC server by installing a debug version of Adobe Flash Player. After you install the debug version of Adobe Flash Player, the log output is stored in a log file under your home directory. (In Windows 7, the log file can be found under C:\Users\username\AppData\Roaming\Macromedia\Flash Player\Logs\flashlog.txt.) Most of the sample request and response content included in the Example sections in Chapter 3 "VNMC XML API Methods" is captured in this manner.
VNMC responds almost immediately to any API request. If the request cannot be completed, a failure is returned. For a query or login method, the actual results are returned. For configuration methods, a successful response indicates that the request is valid, but does not indicate that the operation was completed. For example, after a database backup request is accepted with a successful response from VNMC, the VNMC server might take a longer time to finish the actual backup.
The following sections describe response types in more detail:
Upon a successful response, an XML document is returned with the requested information or a confirmation that changes were made.
The following example shows a configResolveDn request on a policy with the DN org-root/org-tenant d3337/pol-pl:
<configResolveDn cookie="<real_cookie>"
dn="org-root/org-tenant_d3337/pol-p1"
inHierarchical="false"/>
The response includes the following details:
<configResolveDn
dn="org-root/org-tenant_d3337/pol-p1"
cookie="<real_cookie>"
commCookie="7/13/0/a3c"
srcExtSys="10.193.34.70"
destExtSys="10.193.34.70"
srcSvc="sam_extXMLApi"
destSvc="policy-mgr_dme"
response="yes">
<outConfig>
<policyRuleBasedPolicy
descr=""
dn="org-root/org-tenant_d3337/pol-p1"
intId="10811"
name="p1"/>
</outConfig>
</configResolveDn></configResolveDn>
Responses to failed requests include XML attributes for errorCode and errorDescr. The following example shows the response to a failed request that tried to create a policy with the same name as another policy already in the system:
<configConfMo
dn="org-root/org-tenant_d3337/pol-p1"
cookie="<real_cookie>"
commCookie="7/13/0/2038"
srcExtSys="10.193.34.70"
destExtSys="10.193.34.70"
srcSvc="sam_extXMLApi"
destSvc="policy-mgr_dme"
response="yes"
errorCode="103"
invocationResult="unidentified-fail"
errorDescr="can't create; object already exists.">
</configConfMo>
A query request for a nonexistent object is not treated as a failure. If the object does not exist, a success message is returned, but the XML document contains an empty data field, <outConfig> </outConfig>, which indicates that the requested object was not found.
The following example shows resolution by DN on a nonexistent policy:
<configResolveDn
dn="org-root/org-tenant_d3337/pol-p1"
cookie="<real_cookie>"
commCookie="7/13/0/203e"
srcExtSys="10.193.34.70"
destExtSys="10.193.34.70"
srcSvc="sam_extXMLApi"
destSvc="policy-mgr_dme"
response="yes">
<outConfig>
</outConfig>
</configResolveDn>