Overview of the Network Processor

2 Overview of the Network Processor

This chapter provides an overview of the Oracle Communications IP Service Activator Network Processor, and follows a detailed configuration scenario from start to finish using sample service and device models, command-line interface (CLI) document, and final configuration commands.

In order to understand how to use the SDK to support new devices and services in IP Service Activator, you will need an understanding of the Network Processor framework which provides the link between the cartridges and configuration policies, IP Service Activator, and the devices themselves.

Detailed information on configuring and administering the operation of the Network Processor is given in IP Service Activator System Administrator's Guide. Additional information on related topics can be found in the IP Service Activator product documentation or online help.

Introduction

The Network Processor manages communication to and from devices through cartridges. Within the context of IP Service Activator, it performs the conversion of user changes to the configuration of IP Service Activator objects into a set of CLI commands for delivery to devices.

The Network Processor/cartridge architecture is extensible and scalable. Support for new services and devices can be added by creating and deploying new cartridges and cartridge components.

Within the context of Configuration Management, the Network Processor manages the flow of information from a configuration policy (or configlet) to a device, again by performing the conversion of configuration commands into a set of CLI commands for delivery to the device.

Network Processor Concepts

As mentioned above, the Network Processor converts IP Service Activator user changes into CLI commands that can be pushed to the devices. This task is accomplished in a series of steps that make use of key internal structures. These structures include:

Service model: an XML document containing a representation of a device's topology and its service objects and their relationships. Even though there is one Service Model for each device in an IP Service Activator installation which is managed by a Network Processor, the representation of the service objects is device agnostic. The service model is device independent in the sense that the XML schema allows for the description of services in a device-agnostic manner.
Device model: device-specific cartridge XML document derived from the service model. It contains a set of data elements that defines the complete device state. It extends the Network Processor's device model by adding validation rules so that the new service(s) which the cartridge enables can be fully described.
Annotated device model: an XML document that contains the device model, with annotations to indicate the changes in device configuration between the device's state at the last successful configuration push (as persisted in the database), and its expected state (target) after the current configuration is pushed.

Note:

At the time the Network Processor merges the base command document with the service cartridge command documents, the assocIdArray of each command and each nested command in the following sections of the resulting document will be populated with all non-zero assocIds (collected from all the documents to be merged): initialization, preconfig, postconfig, and finalize.

The task of converting user changes to the IP Service Activator object model into CLI commands uses key resources in the Network Processor framework and in the cartridge. These include:

Service model to device model transform: this Java or XQuery transform takes a device-independent XML based service model and from it creates a device-specific XML based device model.
Annotated device model to CLI transform: this Java or XQuery transform takes a device-specific XML based annotated device model and converts it to a CLI document.
DM validation: this script is optional. If present in the cartridge, it is used by the Network Processor to validate the data in the generated device model.

Network Processor and Cartridge Components

Figure 2-1 shows an overview of the Network Processor tasks.

Figure 2-1 Network Processor Task Overview

Description of "Figure 2-1 Network Processor Task Overview"

Process

When a user makes changes to logical policies:

The policy server forwards these changes to the Network Processor that manages the affected device(s).
The Network Processor creates a target service model for each affected device.
The Network Processor determines which vendor cartridge to use for each affected device. It applies the service model to device model transform using the vendor cartridge to create a device model for each affected device.
The Network Processor compares the newly created target device model to the device model that was persisted to its database after the last successful push to that device. An annotated device model contains annotations that indicate whether configuration is being added, deleted, or modified.
The Network Processor runs the annotated device model to CLI transform in the cartridge to create a CLI document. This CLI document contains data elements that represent the commands needed to change the device configuration from its present state to the desired state. That is, the document reflects the delta between the current and desired state.
The Network Processor executes the CLI document and sends the commands to the device via telnet or SSH.
Device responses are interpreted, and feedback is provided on the success or failure of changing the configuration to the desired state.

Once the commands have been successfully sent to the device, the service model and device model are persisted to the database so they can be referred to as the last service and device model in the next transaction committed on the device.

In a scenario in which multiple independent logical policy changes are made affecting the same device, it is possible for some to succeed and others to fail. In such a scenario, the persisted service model and device model will represent the successfully applied configuration changes.

Registering Cartridges with the Network Processor

When a cartridge is installed into a IP Service Activator system, the Network Processor creates a mapping from the information in the XML registry file supplied with the cartridge. When a service is applied to a device, the Network Processor can then determine which cartridge contains the necessary additional components which configure that service. Cartridge registration will be described in detail later on.

Data Flow from a Configuration Policy through the Network Processor and Cartridge

As shown in Figure 1-1, a configuration policy includes two key components:

HTML GUI screen: this is an HTML document defining a data input form for the configuration policy
Schema: this schema defines the data for the particular service that the configuration policy is used to create

When a configuration policy is applied to a device, the IP Service Activator user enters appropriate data for the service into the GUI through the HTML GUI form.

This data is stored in an XML file and is validated by the configuration policy's schema. A valid XML data file is then passed to the policy server which determines which Network Processor manages the targeted device.

The XML data is then managed by the Network Processor in the same manner as described above.

Service Model

This section discusses the details of a service model.

When the Network Processor receives a transaction commit for a device from the IP Service Activator policy server, it constructs a service model. A service model is a normalized representation of the device topology and the logical policies that are applied to it. The service model document contains two major sections: topology information, and definitions of logical policies that are applied to the device.

The sample service model has bold sections. These sections contain the data for the sample configuration that is being pushed. Other bold sections help visually define the structure of the document and emphasize certain data.

Sample Service Model

<ser:device xmlns:ser="http://www.metasolv.com/serviceactivator/servicemodel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <ser:component_id>7020</ser:component_id>
  <ser:component_name>rotgsr-1.kanata.ca.oracle.com</ser:component_name>
  <ser:driver_type>cisco</ser:driver_type>
  <ser:ip_address>178013278</ser:ip_address>
  <ser:authentication_information>

    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.AUTHENTICATION.SNMP_READ_COMMUNITY</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">U2w6VwySz9Q=</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.CISCO.AUTHENTICATION.TACACS</ser:name>
      <ser:value xsi:type="xs:boolean" xmlns:xs="http://www.w3.org/2001/XMLSchema">true</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.CISCO.AUTHENTICATION.TACACS.USER_NAME</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.CISCO.AUTHENTICATION.TACACS.USER_RESPONSES</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.CISCO.AUTHENTICATION.ALL.ENABLE_PASSWORD</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
    </ser:item>
  </
  <ser:configuration_information>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.SNMP.RETRIES</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">2</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.SNMP.TIMEOUT</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">3</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.BGPLOCALAS</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">1</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.MANUAL_CONFIG_MODE</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">0</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.MAX_TRANSACTION_SIZE</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">-1</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.PATTERN_TRANSACTION_SIZE</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">^no\s(?!alias)</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.DEVICE_TYPE</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">Cisco 12008</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.DEVICE_DESCRIPTION</ser:name>
      <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">Cisco Internetwork Operating System Software 
IOS (tm) GS Software (GSR-P-M), Version 12.0(32)S5, RELEASE SOFTWARE (fc2)
Tech</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.COMMAND_DELIVERY_MODE</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">1</ser:value>
    </ser:item>
    <ser:item>
      <ser:name>ORCHESTREAM.GENERIC.CONFIGURATION.DEVICE_STATE</ser:name>
      <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">5</ser:value>
    </ser:item>
    </ser:configuration_information>
  <ser:interface>
    <ser:component_id>7252</ser:component_id>
    <ser:component_name/>
    <ser:interface_definition>
      <ser:discriminator xsi:type="ser:DeviceDriver.InterfaceQuery.InterfaceType">Type_INTERFACE</ser:discriminator>
      <ser:interfaceParameters>
        <ser:interfaceID>7252</ser:interfaceID>
        <ser:if_direction>Dir_OUT</ser:if_direction>
        <ser:if_bandwidth>44210</ser:if_bandwidth>
        <ser:ip_address>0</ser:ip_address>
        <ser:snmp_if_index>3626</ser:snmp_if_index>
        <ser:name>Serial3/0</ser:name>
        <ser:internal_name/>
        <ser:valid_fields>6</ser:valid_fields>
        <ser:snmp_if_type>22</ser:snmp_if_type>
        <ser:if_level>0</ser:if_level>
        <ser:parent_component_id>0</ser:parent_component_id>
        <ser:parent_name/>
        <ser:owned>false</ser:owned>
      </ser:interfaceParameters>
    </ser:interface_definition>
  <ser:interface>
    <ser:component_id>7252</ser:component_id>
    <ser:component_name/>
    <ser:interface_definition>
      <ser:discriminator xsi:type="ser:DeviceDriver.InterfaceQuery.InterfaceType">Type_INTERFACE</ser:discriminator>
      <ser:interfaceParameters>
        <ser:interfaceID>7252</ser:interfaceID>
        <ser:if_direction>Dir_OUT</ser:if_direction>
        <ser:if_bandwidth>44210</ser:if_bandwidth>
        <ser:ip_address>0</ser:ip_address>
        <ser:snmp_if_index>3626</ser:snmp_if_index>
        <ser:name>Serial3/0</ser:name>
        <ser:internal_name/>
        <ser:valid_fields>6</ser:valid_fields>
        <ser:snmp_if_type>22</ser:snmp_if_type>
        <ser:if_level>0</ser:if_level>
        <ser:parent_component_id>0</ser:parent_component_id>
        <ser:parent_name/>
        <ser:owned>false</ser:owned>
      </ser:interfaceParameters>
    </ser:interface_definition>
    <ser:associations>
      <ser:item xsi:type="ser:NetworkProcessor.Association">
        <ser:id>
          <ser:id>1578</ser:id>
          <ser:ver>0</ser:ver>
        </ser:id>
        <ser:assoc_id>7432</ser:assoc_id>
        <ser:outbound>true</ser:outbound>
      </ser:item>
      <ser:item xsi:type="ser:NetworkProcessor.Association">
        <ser:id>
          <ser:id>7460</ser:id>
          <ser:ver>0</ser:ver>
        </ser:id>
        <ser:assoc_id>7462</ser:assoc_id>
        <ser:outbound>true</ser:outbound>
      </ser:item>
    </ser:associations>
  </ser:interface>
<ser:associations>
    <ser:item>
      <ser:id>
        <ser:id>7020</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:assoc_id>0</ser:assoc_id>
    </ser:item>
    <ser:item>
      <ser:id>
        <ser:id>1082</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:assoc_id>0</ser:assoc_id>
    </ser:item>
  </ser:associations>
<ser:definitions>
    <ser:item>
      <ser:id>
        <ser:id>7020</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>OCH_DeviceParameters</ser:name>
      <ser:value>
        <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">ParameterSetDefinitionType</ser:discriminator>
        <ser:parameter_set>
          <ser:item>
            <ser:name>OCH_AuthSnmpReadComm</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">U2w6VwySz9Q=</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_AuthTacacsEnabled</ser:name>
            <ser:value xsi:type="xs:boolean" xmlns:xs="http://www.w3.org/2001/XMLSchema">true</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_AuthTacacsUsername</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
          </ser:item>
          <ser:item>
            <ser:name>OCH_AuthTacacsResponses</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
          </ser:item>
          <ser:item>
            <ser:name>OCH_AuthEnablePw</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema"/>
          </ser:item>
          <ser:item>
            <ser:name>OCH_BgpLocalAs</ser:name>
            <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">1</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_ManualConfigMode</ser:name>
            <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">0</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_MaxTransactionSize</ser:name>
            <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">-1</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_PatternTransactionSize</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">^no\s(?!alias)</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_CommandDeliveryMode</ser:name>
            <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">1</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_DeviceState</ser:name>
            <ser:value xsi:type="xs:long" xmlns:xs="http://www.w3.org/2001/XMLSchema">5</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_NetflowSourceInterface</ser:name>
            <ser:value xsi:type="xs:string" xmlns:xs="http://www.w3.org/2001/XMLSchema">loopback0</ser:value>
          </ser:item>
          <ser:item>
            <ser:name>OCH_SAARtrResponder</ser:name>
            <ser:value xsi:type="xs:boolean" xmlns:xs="http://www.w3.org/2001/XMLSchema">false</ser:value>
          </ser:item>
        </ser:parameter_set>
      </ser:value>
      <ser:options/>
    </ser:item>
    <ser:item>
      <ser:id>
        <ser:id>1578</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>netflowCollector</ser:name>
      <ser:value>
        <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">GenericRuleDefinitionType</ser:discriminator>
        <ser:generic_rule_def>
          <ser:contentType>collectorParameters</ser:contentType>
          <ser:contentValue>
            <collectorParameters xmlns="http://www.metasolv.com/serviceactivator/collectorParameters">
              <type>Cisco Netflow FlowCollector</type>
              <externalSystem>
                <primaryIP>
                  <ipAddress>3.3.3.3</ipAddress>
                  <port>32</port>
                </primaryIP>
              </externalSystem>
            </collectorParameters>
          </ser:contentValue>
          <ser:rule_directives/>
          <ser:order>4026531840</ser:order>
        </ser:generic_rule_def>
      </ser:value>
    <ser:options/>
    </ser:item>

    <ser:item>
      <ser:id>
        <ser:id>1082</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>myDomain</ser:name>
      <ser:value>
        <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">IBgpBaseDefinitionType</ser:discriminator>
        <ser:ibgp_base_definition>
          <ser:configure>false</ser:configure>
          <ser:internal_asn>1</ser:internal_asn>
          <ser:max_paths>1</ser:max_paths>
          <ser:update_source>0</ser:update_source>
          <ser:std_communities>true</ser:std_communities>
          <ser:md5_authentication/>
        </ser:ibgp_base_definition>
      </ser:value>
      <ser:options/>
    </ser:item>
    <ser:item>
      <ser:id>
        <ser:id>7460</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>static route</ser:name>
      <ser:value>
        <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">GenericRuleDefinitionType</ser:discriminator>
        <ser:generic_rule_def>
          <ser:contentType>staticRoutes</ser:contentType>
          <ser:contentValue>
            <staticRoutes xmlns="http://www.metasolv.com/serviceactivator/staticroute">
              <staticRoute>
                <ip>20.20.20.20</ip>
                <mask>32</mask>
                <next_hop_ip>21.21.21.21</next_hop_ip>
                <distance_metric>3</distance_metric>
              </staticRoute>
            </staticRoutes>
          </ser:contentValue>
          <ser:rule_directives/>
          <ser:order>805306368</ser:order>
        </ser:generic_rule_def>
      </ser:value>
      <ser:options/>
    </ser:item>
  </ser:definitions>
</ser:device>

Key sections in the sample service model are:

component_id: unique ID of the device
component_name: name of device
driver_type: family of devices that this device belongs to.

Note:

In order for the Network Processor to determine which cartridge instance to invoke to process the service model, it compares the driver type against the registry of cartridges, searching for a cartridge instance that administers this driver type. When found it will invoke the entries indicated by the cartridge instance.
ip_address: IP address of the device
authentication_information: information about login credentials of the device
configuration_information: information on network processor behavior to implement for this device
device topology: this is the target of a definition
- device (implied): physical hardware representation of the device
- device associations: links to the logical policies that are applied to this device. The link is made using the logical policy's definition ID.
interface topology: physical hardware or software representation of an interface
- interface associations: links to logical policies that are applied to this interface. The link is made using the logical policy's definition ID.
definitions: listing of logical policies that are applied to the device and/or interfaces
- id: value which uniquely identifies the logical policy in the service model.
- name: name of logical policy
- value: details of the logical policy

Definitions and Associations

As mentioned above, the service model contains topology information and definitions of logical policies that are applied to the device. It also contains information which describes the relationships between the logical policies and the objects to which they apply.

A definition, in the context of a service model, defines a logical policy.

A definition ID is a value which uniquely identifies a particular logical policy in the service model.

An association in the service model links a logical policy definition with an object (e.g. device or interface).

An association ID is a value which uniquely identifies the association. The association ID is also used in the Network Processor to link the object with the concrete representing the logical policy in the IP Service Activator core.

Note:

Both the service model to device model and annotated device model to CLI transforms must correctly carry association IDs from the source to the target models. If this is not done correctly, quarantine, failure notifications, and faults will not operate correctly. These will be described in more detail later in this document.

Sample Service Model Associations

This section illustrates how logical policies are associated with objects in the service model using associations.

The following service model snippet from the service model example contains the definition of a logical policy called netflowCollector.

    <ser:item>
      <ser:id>
        <ser:id>1578</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>netflowCollector</ser:name>
      <ser:value>
      <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">GenericRuleDefinitionType</ser:discriminator>
        <ser:generic_rule_def>
          <ser:contentType>collectorParameters</ser:contentType>
          <ser:contentValue>
            <collectorParameters xmlns="http://www.metasolv.com/serviceactivator/collectorParameters">
              <type>Cisco Netflow FlowCollector</type>
              <externalSystem>
                <primaryIP>
                  <ipAddress>3.3.3.3</ipAddress>
                  <port>32</port>
                </primaryIP>
              </externalSystem>
            </collectorParameters>
          </ser:contentValue>
          <ser:rule_directives/>
          <ser:order>4026531840</ser:order>
        </ser:generic_rule_def>
      </ser:value>
    <ser:options/>
    </ser:item>

Note that the id section of this logical policy contains the definition ID of 1578. As well, the name is specified just below as netflowCollector.

This snippet from the same service model shows a static route logical policy definition.

    <ser:item>
      <ser:id>
        <ser:id>7460</ser:id>
        <ser:ver>1</ser:ver>
      </ser:id>
      <ser:name>static route</ser:name>
      <ser:value>
        <ser:discriminator xsi:type="ser:DefinitionSite.DefinitionType">GenericRuleDefinitionType</ser:discriminator>
        <ser:generic_rule_def>
          <ser:contentType>staticRoutes</ser:contentType>
          <ser:contentValue>
            <staticRoutes xmlns="http://www.metasolv.com/serviceactivator/staticroute">
              <staticRoute>
                <ip>20.20.20.20</ip>
                <mask>32</mask>
                <next_hop_ip>21.21.21.21</next_hop_ip>
                <distance_metric>3</distance_metric>
              </staticRoute>
            </staticRoutes>
          </ser:contentValue>
          <ser:rule_directives/>
          <ser:order>805306368</ser:order>
        </ser:generic_rule_def>
      </ser:value>
      <ser:options/>
    </ser:item>

Note that the id section of this logical policy contains the definition ID of 7460. As well, the name is specified just below as static route.

The snippet of the example service model below contains the associations of these logical policies with an interface.

  <ser:interface>
. . .
    <ser:associations>
      <ser:item xsi:type="ser:NetworkProcessor.Association">
        <ser:id>
          <ser:id>1578</ser:id>
          <ser:ver>0</ser:ver>
        </ser:id>
        <ser:assoc_id>7432</ser:assoc_id>
        <ser:outbound>true</ser:outbound>
      </ser:item>
      <ser:item xsi:type="ser:NetworkProcessor.Association">
        <ser:id>
          <ser:id>7460</ser:id>
          <ser:ver>0</ser:ver>
        </ser:id>
        <ser:assoc_id>7462</ser:assoc_id>
        <ser:outbound>true</ser:outbound>
      </ser:item>
    </ser:associations>
  </ser:interface>

For this interface, two associations are present. The first association has the association ID of 7432. This association has the definition id value of 1578. This means that the logical policy with the definition ID of 1578 is applied to this interface. Looking at the definition snippet above, we can confirm that 1578 identifies the netflow collector policy.

Similarly, the second association has the association ID of 7462. This association has the definition id value of 7460. This means that the logical policy with the definition ID of 7460 is applied to this interface. Again, looking at the second definition snippet above, we can confirm that 7460 identifies the static route policy.

Device Model

This section discusses the makeup of a device model.

A device model is a device-specific XML document derived from the service model. It contains a set of data elements that defines the complete device state.

A device model is an extension of the base device model provided by the Network Processor. This extension to the base device model schema is contained in the cartridge and is typically called deviceModel.xsd. A device model instance is validated using the deviceModel.xsd and base_devicemodel.xsd at run time.

The sample device model has highlighted sections similar to the sample service model.

Sample Device Model

<lib:device xsi:type="dm:CiscoDevice" xmlns:lib="http://www.metasolv.com/serviceactivator/devicemodel" xmlns:dm="http://www.metasolv.com/serviceactivator/cisco" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <lib:appInfo>
    <lib:version>2.3.0</lib:version>
  </lib:appInfo>
  <lib:componentId>7020</lib:componentId>
  <lib:componentName>rotgsr-1.kanata.ca.oracle.com</lib:componentName>
  <lib:driverType>cisco</lib:driverType>
  <lib:configurationInfo>
    <lib:deviceType>Cisco 12008</lib:deviceType>
    <lib:deviceDescription>Cisco Internetwork Operating System Software 
IOS (tm) GS Software (GSR-P-M), Version 12.0(32)S5, RELEASE SOFTWARE (fc2)
Tech</lib:deviceDescription>
    <lib:cartridgeObjid>49</lib:cartridgeObjid>
  </lib:configurationInfo>
  <lib:ipAddress>10.156.68.94</lib:ipAddress>
  <lib:generationId>5</lib:generationId>
  <lib:configlets/>
  <lib:interfaces>
    <lib:interface xsi:type="dm:CiscoInterface">
      <lib:id>7252</lib:id>
      <lib:name>Serial3/0</lib:name>
      <dm:bandwidth>44210</dm:bandwidth>
    </lib:interface>
  </lib:interfaces>
  <lib:configVersion>
    <lib:assoc_id>0</lib:assoc_id>
    <lib:timestamp>2007-11-07T15:15:23.177Z</lib:timestamp>
  </lib:configVersion>
  <lib:schedules/>
  <dm:prefixLists/>
  <dm:staticRoutes>
    <dm:staticRoute smId="7460">
      <lib:assoc_id>7462</lib:assoc_id>
      <dm:networkAddress>20.20.20.20</dm:networkAddress>
      <dm:networkMask>32</dm:networkMask>
      <dm:nextHopIp>21.21.21.21</dm:nextHopIp>
      <dm:distanceMetric>3</dm:distanceMetric>
    </dm:staticRoute>
  </dm:staticRoutes>
  <dm:rtrs/>
<dm:netFlow>
    <dm:export-destinations>
      <dm:export-destination smId="1578">
        <lib:assoc_id>7432</lib:assoc_id>
        <dm:ipAddress>3.3.3.3</dm:ipAddress>
        <dm:port>32</dm:port>
      </dm:export-destination>
    </dm:export-destinations>
  </dm:netFlow>
  <dm:fwModuleGroups/>  <dm:aceModuleGroups/>
</lib:device>

Device Model and the Service Model to Device Model Transform

The first transform step is for the service model to be transformed to the device model. To do this, the Network Processor invokes the <smToDm> entry that is pointed to in the cartridge instance.

Using the cartridge-supplied transform, the network processor transforms the service model to a device, which is a device/vendor-specific model derived from the service model.

The sm2Dm is an Java or XQuery file that navigates the service model and reorganizes the information into the device model document. In addition to the basic conversion to device model, additional processing such as logic to invoke options, may be included at the developers discretion. If the transform is a java transform, then use <smToDm transformType="java"> as the entry.

Sample Relating the Service Model to the Device Model

This section shows how key portions of the service model in "Sample Service Model" are transformed to the device model in "Sample Device Model". Logical policies and the objects they are applied to are shown as discrete configuration sections.

netFlow

In this example, you can see the netflow element that combines the netflow logical policy with the configuration details. For the sample services (netflow and static route) although the service is applied conceptually at the interface level, the configuration command is given at the device level.

The example contains references to the unique service model association id (7432) and the logical policy definition smId (1578) which together generated the following configuration. It also contains relevant configuration data for IP address and port from the logical policy.

  <dm:netFlow>
    <dm:export-destinations>
      <dm:export-destination smId="1578">
        <lib:assoc_id>7432</lib:assoc_id>
        <dm:ipAddress>3.3.3.3</dm:ipAddress>
        <dm:port>32</dm:port>
      </dm:export-destination>
    </dm:export-destinations>
  </dm:netFlow>

staticRoute

In this example, you can see the static route element that combines the static route logical policy with the details for the particular interface to which it applies. It contains references to the unique service model association id (7462) and the logical policy definition smId (7460) which together generated the following configuration. It also contains relevant configuration data for network address, network mask, nextHopIp, and distanceMetric from the logical policy.

  <dm:staticRoutes>
    <dm:staticRoute smId="7460">
      <lib:assoc_id>7462</lib:assoc_id>
      <dm:networkAddress>20.20.20.20</dm:networkAddress>
      <dm:networkMask>32</dm:networkMask>
      <dm:nextHopIp>21.21.21.21</dm:nextHopIp>
      <dm:distanceMetric>3</dm:distanceMetric>
    </dm:staticRoute>
  </dm:staticRoutes>

Device Model Validation

If the cartridge registry entry <dmValidation> contains a dmValidation entry, the Network Processor will invoke this function to validate the transformed device model. This would capture logical faults as opposed to syntax faults which would be caught by the device model validation using deviceModel.xsd. If the transform is a java transform, then use <dmValidation transformType="java"> as the entry.

Sample Annotated Device Model

The Network Processor compares the target device model against the last pushed device model that was persisted after the last successful push to the device.

The target device model is compared or annotated against the last pushed device model yielding the annotated device model, which annotates the changes needed to the device's configuration to end up with the configuration desired.

Below is a sample of the annotated device model:

<lib:device xsi:type="dm:CiscoDevice" xmlns:lib="http://www.metasolv.com/serviceactivator/devicemodel" xmlns:dm="http://www.metasolv.com/serviceactivator/cisco" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <lib:appInfo>
    <lib:version>2.3.0</lib:version>
  </lib:appInfo>
  <lib:componentId>7020</lib:componentId>
  <lib:componentName>rotgsr-1.kanata.ca.oracle.com</lib:componentName>
  <lib:driverType>cisco</lib:driverType>
  <lib:configurationInfo>
    <lib:deviceType>Cisco 12008</lib:deviceType>
    <lib:deviceDescription>Cisco Internetwork Operating System Software 
IOS (tm) GS Software (GSR-P-M), Version 12.0(32)S5, RELEASE SOFTWARE (fc2)
Tech</lib:deviceDescription>
    <lib:cartridgeObjid>49</lib:cartridgeObjid>
  </lib:configurationInfo>
  <lib:ipAddress>10.156.68.94</lib:ipAddress>
  <lib:generationId>5</lib:generationId>
  <lib:authenticationTacacs>
    <lib:userName/>
    <lib:password/>
    <lib:enablePassword/>
  </lib:authenticationTacacs>
  <lib:configlets/>
  <lib:interfaces>
    <lib:interface xsi:type="dm:CiscoInterface">
      <lib:id>7252</lib:id>
      <lib:name>Serial3/0</lib:name>
      <dm:bandwidth>44210</dm:bandwidth>
    </lib:interface>
  </lib:interfaces>
  <lib:configVersion dmId="1" changeType="ADD">
    <lib:assoc_id>7432</lib:assoc_id>
    <lib:assoc_id>7462</lib:assoc_id>
    <lib:timestamp>2007-11-07T15:15:23.177Z</lib:timestamp>
  </lib:configVersion>
  <lib:schedules/>
  <dm:prefixLists/>
<dm:staticRoutes>
    <dm:staticRoute smId="7460" dmId="2" changeType="ADD">
      <lib:assoc_id>7462</lib:assoc_id>
      <dm:networkAddress>20.20.20.20</dm:networkAddress>
      <dm:networkMask>32</dm:networkMask>
      <dm:nextHopIp>21.21.21.21</dm:nextHopIp>
      <dm:distanceMetric>3</dm:distanceMetric>
    </dm:staticRoute>
  </dm:staticRoutes>
  <dm:rtrs/>
<dm:netFlow>
    <dm:export-destinations>
      <dm:export-destination smId="1578" dmId="3" changeType="ADD">
        <lib:assoc_id>7432</lib:assoc_id>
        <dm:ipAddress>3.3.3.3</dm:ipAddress>
        <dm:port>32</dm:port>
      </dm:export-destination>
    </dm:export-destinations>
  </dm:netFlow>
  <dm:fwModuleGroups/>
  <dm:aceModuleGroups/>
</lib:device>

Sample Relating the Device Model to the Annotated Device Model

The Network Processor, after comparing the target device model with the last pushed device model, has annotated the device model with these attributes:

smId - definition ID from the service model
dmId - device model ID which is created for each command entry to be applied. This ID is generated by the Network Processor by invoking the annotation.
changeType - attribute indicating the change type: adding, deleting or modifying configuration

The configuration data on the interfaces have been carried forward from previous examples; IP address and port from the netFlow configuration, and networkAddress, networkMask, nextHopIp and distanceMetric from the static route configuration.

<dm:netFlow>
    <dm:export-destinations>
      <dm:export-destination smId="1578" dmId="3" changeType="ADD">
        <lib:assoc_id>7432</lib:assoc_id>
        <dm:ipAddress>3.3.3.3</dm:ipAddress>
        <dm:port>32</dm:port>
      </dm:export-destination>
    </dm:export-destinations>
  </dm:netFlow>
. . .
<dm:staticRoutes>
    <dm:staticRoute smId="7460" dmId="2" changeType="ADD">
      <lib:assoc_id>7462</lib:assoc_id>
      <dm:networkAddress>20.20.20.20</dm:networkAddress>
      <dm:networkMask>32</dm:networkMask>
      <dm:nextHopIp>21.21.21.21</dm:nextHopIp>
      <dm:distanceMetric>3</dm:distanceMetric>
    </dm:staticRoute>
  </dm:staticRoutes>

Note:

The service model showed that the logical policies were applied to specific interfaces. When you read the device model it may appear that information is missing. Static routes and netflow configuration happen to be configured on the target device type as device level commands, rather than being configured against interfaces. Therefore the static route and netflow information don't show as child elements to interfaces in the device model.

The application of these logical policies on interfaces at the GUI is simply a human viewable artifact that been translated to a device level artifact.

Sample CLI Commands and the Device Model to CLI Transform

The next step is for the annotated device model to be transformed to the CLI commands. To do this, the Network Processor invokes the <dmToCli> entry that is pointed to in the cartridge instance. If the transform is a java transform, then use <dmToCli transformType="java"> as the entry.

Using the cartridge-supplied transform, the Network Processor transforms the annotated device model to a CLI document, which is a list of native configuration commands to be sent to the device.

The annotated dm2Cli is an Java or XQuery file that navigates the annotated device model and reorganizes the information into the CLI document. In addition to the basic conversion to CLI, additional processing such as logic to invoke options, may be included at the developers discretion.

Sample CLI Document

<cmd:commandSession xmlns:cmd="http://www.metasolv.com/serviceactivator/climodel">
  <cmd:configuration>
    <cmd:ipAddress>10.156.68.94</cmd:ipAddress>
    <cmd:prompt>
      <cmd:matchPattern>([^>#\n]*)[>#]</cmd:matchPattern>
      <cmd:prependPattern>\n</cmd:prependPattern>
      <cmd:appendPattern>(([>#])|(\(.*\)#))</cmd:appendPattern>
      <cmd:errorPattern>.*Username:</cmd:errorPattern>
      <cmd:hostPattern>[\w\.\-]+</cmd:hostPattern>
    </cmd:prompt>
    <cmd:errorPatterns>
      <!--Cisco and frameworkTest-cu1 Error Messages-->
      <cmd:errorPattern>
        <cmd:pattern>(?s).*Invalid input.*</cmd:pattern>
        <cmd:message>Invalid input</cmd:message>
      </cmd:errorPattern>
    </cmd:errorPatterns>
    <cmd:warningPatterns>
      <!--in theory, we could ignore this and continue. The problem is, we get the same message when removing the policing rule. This means a user could see the warning, correct the problem, and then see the warning pop back-->
      <cmd:warningPattern blocking="true">
        <cmd:pattern>(?s).*Illegal .* burst size.*Increasing .* burst size.*</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*WARNING: \"ip multicast-routing\" is not configured.*</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*WARNING: CGMP requires PIM enabled on interface</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*WARNING: RGMP requires PIM enabled on interface</cmd:pattern>
      </cmd:warningPattern>
      <!--This message indicates "copy running-config startup-config" has failed. This will produce a warning instead of failing and rolling back commands.-->
      <cmd:warningPattern>
        <cmd:pattern>(?s).*startup-config file open failed.*</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <!--cisco: message after Policy Map configured with bandwidth greater than available"-->
        <cmd:pattern>(?s).*bandwidth is less than requested.*</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <!--cisco: message after configuring two instances of the export destination commands with the same IP address a warning is received (NetFlow)"-->
        <cmd:pattern>(?s).*Second destination address is the same as previous address.*</cmd:pattern>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*Warning: portfast should only be enabled on ports connected to a single.*</cmd:pattern>
        <cmd:message>portfast should only be enabled on ports connected to a single host. Connecting hubs, concentrators, switches, bridges, etc... to this interface when portfast is enabled, can cause temporary bridging loops.</cmd:message>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*Command rejected: .* is a routed port.*</cmd:pattern>
        <cmd:message>Command rejected: port is a routed port.</cmd:message>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*(w|W)arning: trust value is ignored in 'mls qos queueing-only' mode.*</cmd:pattern>
        <cmd:message>Trust value is ignored in 'mls qos queueing-only' mode.</cmd:message>
      </cmd:warningPattern>
      <cmd:warningPattern>
        <cmd:pattern>(?s).*Receive Threshold enabled.*</cmd:pattern>
        <cmd:message>Receive Threshold enabled.</cmd:message>
      </cmd:warningPattern>
    </cmd:warningPatterns>
    <cmd:successPatterns>
      <!--CISCO MESSAGES-->
      <cmd:successPattern>
        <!---reference a policy map that is already applied to this interface-->
        <cmd:pattern>(?s).*QoS policy .+ is already applied.(\\n.*|$)</cmd:pattern>
      </cmd:successPattern>
      <cmd:successPattern>
        <!---cisco : message after "conf t"-->
        <cmd:pattern>(?s).*Enter configuration commands, one per line\..*</cmd:pattern>
      </cmd:successPattern>
      <cmd:successPattern>
        <!---cisco : message after "no interface"-->
        <cmd:pattern>(?s).*Not all config may be removed.*</cmd:pattern>
      </cmd:successPattern>
      <cmd:successPattern>
        <!---cisco : message after "no ip vrf "-->
        <cmd:pattern>(?s).*IP addresses from all interfaces in VRF .* have been removed.*</cmd:pattern>
      </cmd:successPattern>
    </cmd:successPatterns>
  </cmd:configuration>
  <cmd:authentication>
    <cmd:prompt>.*Username:</cmd:prompt>
    <cmd:response/>
  </cmd:authentication>
  <cmd:authentication>
    <cmd:prompt>.*Password:</cmd:prompt>
    <cmd:response/>
    <cmd:errorPrompt>.*Username:</cmd:errorPrompt>
  </cmd:authentication>
  <cmd:initialization>
    <cmd:command alwaysRetry="true">
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:commandString>terminal length 0</cmd:commandString>
    </cmd:command>
  </cmd:initialization>
  <cmd:precheck/>
  <cmd:preconfig>
    <cmd:command alwaysRetry="true">
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:retry>
        <cmd:retryNumber>2</cmd:retryNumber>
        <cmd:waitTime>20</cmd:waitTime>
      </cmd:retry>
      <cmd:commandString>conf t</cmd:commandString>
    </cmd:command>
  </cmd:preconfig>
<cmd:command dmId="3">
    <cmd:assoc_id>7432</cmd:assoc_id>
    <cmd:commandString>ip flow-export destination 3.3.3.3 32</cmd:commandString>
  </cmd:command>
  <cmd:command dmId="2">
    <cmd:assoc_id>7462</cmd:assoc_id>
    <cmd:commandString>ip route 20.20.20.20 32 21.21.21.21 3</cmd:commandString>
  </cmd:command>
  <cmd:postconfig>
    <cmd:command dmId="1" configVersion="true">
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:commandString>alias exec IpsaConfigVersion 2007-11-07T15:15:23.177Z</cmd:commandString>
    </cmd:command>
    <cmd:command alwaysRetry="true">
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:commandString>end</cmd:commandString>
    </cmd:command>
  </cmd:postconfig>
  <cmd:postcheck/>
  <cmd:finalize>
    <cmd:command>
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:commandString>copy running-config startup-config</cmd:commandString>
      <cmd:conditionalPrompt>.*Destination filename.*</cmd:conditionalPrompt>
      <cmd:conditionalCommand>
        <cmd:assoc_id>7432</cmd:assoc_id>
        <cmd:assoc_id>7462</cmd:assoc_id>
        <cmd:commandString>startup-config</cmd:commandString>
        <cmd:conditionalPrompt>.*Overwrite the previous NVRAM configuration?.*</cmd:conditionalPrompt>
        <cmd:conditionalCommand>
          <cmd:assoc_id>7432</cmd:assoc_id>
          <cmd:assoc_id>7462</cmd:assoc_id>
          <cmd:commandString>y</cmd:commandString>
        </cmd:conditionalCommand>
        <cmd:timeoutSeconds>600</cmd:timeoutSeconds>
      </cmd:conditionalCommand>
      <cmd:timeoutSeconds>600</cmd:timeoutSeconds>
    </cmd:command>
    <cmd:command>
      <cmd:assoc_id>7432</cmd:assoc_id>
      <cmd:assoc_id>7462</cmd:assoc_id>
      <cmd:commandString>logout</cmd:commandString>
      <cmd:conditionalPrompt>.*</cmd:conditionalPrompt>
    </cmd:command>
  </cmd:finalize>
</cmd:commandSession>

Key sections in the CLI document are:

Configuration: information on network processor behavior to implement for this device
- ipAddress: IP address of the device
- prompt: the device prompt
- errorPatterns: device response error pattern
- warningPatterns: device response warning pattern
- successPatterns: device response success pattern
Authentication: information about login credentials of the device
Initialization: commands that may need to be applied to the device as an extended part of the login/setup phase.
Precheck: commands for checking and validating existing configuration on the device.
Preconfig: commands needed before the configuration can take place.
Command: this section contains the actual configuration commands for the changing services
Postconfig: commands that must be issued once configuration is completed.
Finalize: commands to be issued once all other configuration and checks are complete.

CLI Elements

Several new elements have been added to the CLI document to allow cartridges to handle some of the variations in communications with devices. Some of the new items added allow you to:

Specify a terminal type (VT100 is used by default)
Specify a line terminator (\n is used by default)
Flush buffers

Sample Relating the Annotated Device Model to the CLI Document

In the sample, we can see that the configuration parameters have reached the CLI stage.

The snippet below contains the dmIDs assigned by the Network Processor, and the final configuration commands based on the original logical policies and interfaces they were applied to.

<cmd:command dmId="3">
    <cmd:assoc_id>7432</cmd:assoc_id>
    <cmd:commandString>ip flow-export destination 3.3.3.3 32</cmd:commandString>
  </cmd:command>
  <cmd:command dmId="2">
    <cmd:assoc_id>7462</cmd:assoc_id>
    <cmd:commandString>ip route 20.20.20.20 32 21.21.21.21 3</cmd:commandString>
  </cmd:command>

CLI Merging

The CLI models generated by the core/base and service cartridges will all be merged before commands are sent to the device. The CLI models can be broken up into separate sections, each of which is merged together. This provides a means of ordering the commands between the various cartridges.

Merge Section Descriptions

The following lists the merge sections available and what type of commands are expected to be in each:

Initialization: commands that may need to be applied to the device as an extended part of the login/setup phase. This phase does not perform any configuration related activities.
Pre-check: commands for checking and validating existing configuration on the device. This should not perform any configuration.
Preconfig: commands needed before the configuration can take place. This is usually commands needed to put the device into a special mode for accepting new configuration.
DeleteConfig: This section is for deleting configuration from the device. This configuration cannot include configuration that removes interfaces.
CreateInterface: special section for creating interfaces.
Command: special section used by the core cartridges for applying configuration. Should not be used by SDK developers.
DeleteInterface: section for deleting interfaces. The configuration on these interfaces must be separately removed in the “deleteConfig" section.
CreateConfig: section for creating or overwriting configuration. This section cannot create interfaces.
Postconfig: commands that must be issued once configuration is completed. Normally, this is commands to get out of the configuration mode.
Postcheck: commands for validating the configuration applied to the device.
Finalize: commands to be issued once all other configuration and checks are complete. This usually includes commands for saving the configuration on the device.

Sample Relating the CLI Document to Configuration Commands

Continuing the example to the configuration stage, the Network Processor command executor (see "Command Executor") would send the following commands to provision the sample netflow collector and static route:

ip flow-export destination 3.3.3.3 32
ip route 20.20.20.20 32 21.21.21.21 3

The auditTrails would show the following:

2007-11-07 10:15:23|10.156.68.94|#Start Configuration
2007-11-07 10:15:23|10.156.68.94|file-interface|#Applying Configuration
2007-11-07 10:15:23|10.156.68.94|file-interface|terminal length 0
2007-11-07 10:15:23|10.156.68.94|file-interface|conf t
2007-11-07 10:15:23|10.156.68.94|file-interface|ip flow-export destination 3.3.3.3 32
2007-11-07 10:15:23|10.156.68.94|file-interface|ip route 20.20.20.20 32 21.21.21.21 3
2007-11-07 10:15:23|10.156.68.94|file-interface|alias exec IpsaConfigVersion 2007-11-07T15:15:23.177Z
2007-11-07 10:15:23|10.156.68.94|file-interface|end
2007-11-07 10:15:23|10.156.68.94|file-interface|copy running-config startup-config
2007-11-07 10:15:23|10.156.68.94|file-interface|logout
2007-11-07 10:15:23|10.156.68.94|#End Configuration

If the configuration is successful, a message is sent back to the policy server indicating that associations 7432 and 7462 have been successfully installed. The service model and the device model are then persisted to the database.

Command Executor

Once the CLI document is constructed the Network Processor command executor is invoked to read the CLI and execute the command elements. Its functionality includes managing logging in to a device, command delivery, recognizing success or failure of commands and other housekeeping related to command delivery.

The default command executor provides standard telnet or ssh access to a device and delivers commandString (which is a child element of command) content to the device. For example:

<cmd:commandString>conf t</cmd:commandString>

Network Processor End to End Flow-Through Illustration

Figure 2-2 illustrates the completed data flow-through described in the preceding pages in this document.

Figure 2-2 Network Processor End to End Flow-Through

Description of "Figure 2-2 Network Processor End to End Flow-Through"

Device Model Extension

The Network Processor comes with a base_devicemodel.xsd which defines the base device model. Consider this to be a common set of device model information for all device models.

Cartridges generally extend this base_deviceModel.xsd to include details of new services that are to be administered.

Changeables and Identifiables

When writing commands to a device, there are three possible user actions:

Add: adding a command to the device
Delete: deleting a command from the device
Modify: modifying an existing command on the device by overwriting it.

In order for a cartridge to support these actions, metadata (changeType) is added to the device model to indicate what action is taking place, which occurs in the annotate device model stage. The target device model shows what the intended device model looks like. The annotated device model shows what is being added/deleted/modified in comparison to the previously pushed device model.

To identify if a command or a command field is addable, deleteable, and or modifiable, in extending the device model, you need to specify what aspects of the device extension are changeable.

Change Types

ChangeTypes are attributes inserted into the device model during the annotation process. They specify which configuration is to be added or deleted.

The cartridge implementation then uses these attributes to decide how to send the configuration to the device.

Generally speaking, when you write your device model, you will be adding content that models the configuration (commands) that you are administering. As part of that model, if the commands are add-able and delete-able you need to mark those commands as “changeable" This is done by extending “lib:Changeable" found in the base_devicemodel.xsd. This allows the Network Processor to annotate the device model with changeType attributes for the purpose of identifying what action is taking place.

Example

n the device model fragment seen below, if the target device model has redistributeStatic and the last device model does not, then redistributeStatic would be annotated as add.

If the target device model does not have redistributeStatic and the last device model does, then redistributeStatic would be annotated with delete.

If the target device model has redistributeStatic and the last device model has redistributeStatic and its value has changed, then redistributeStatic would be annotated with delete and add. The cartridge, in this case, would be expected to send both a delete command followed by an add command to the device to realize the target configuration.

If the target device model has redistributeStatic and the last device model has redistributeStatic and its value has not changed, then redistributeStatic would not be annotated with attribute changeType.

As example, all the elements in the complex type EigrpVrfAddressFamily are changeable.

<xs:complexType name="EigrpVrfAddressFamily">
  <xs:complexContent>
    <xs:extension base="lib:Changeable">
      <xs:sequence>
        <xs:element name="vrfRef" type="xs:string"/>
        <xs:element name="vrfRdRef" type="dm:VpnTag"/>
        <xs:element name="redistributeStatic" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="redistributeConnected" type="dm:RedistributeProtocol" minOccurs="0"/>                    
        <xs:element name="redistributeBgp" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="redistributeRip" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="networkStatements" type="dm:NetworkStatements" minOccurs="0"/>
        <xs:element name="autoSummary" type="dm:ChangeableBoolean" minOccurs="0"/>
        <xs:element name="autonomousSystem" type="xs:unsignedInt"/>
        <xs:element name="maximumPaths" type="dm:ChangeableInteger" minOccurs="0"/>
        <xs:element name="logNeighbourChanges" type="dm:ChangeableBoolean" minOccurs="0"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

When the Network Processor executes the annotation, it will mark each of the above elements with add or delete or nothing based on the action taking place.

Changeable and Identifiable

If a command can be added, deleted and/or modified then you need to further model that command as changeable and identifiable.

Identifiable is terminology that conveys what aspect of the command is modifiable. This is done by extending lib:Container found in base_devicemodel.xsd.

Example

A complex type EigrpVrfAddressFamily extends lib:Changeable, so all these elements can be annotated as added/deleted.

<xs:complexType name="EigrpVrfAddressFamily">
  <xs:complexContent>
    <xs:extension base="lib:Changeable">
      <xs:sequence>
        <xs:element name="vrfRef" type="xs:string"/>
        <xs:element name="vrfRdRef" type="dm:VpnTag"/>
        <xs:element name="redistributeStatic" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="redistributeConnected" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="redistributeBgp" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="redistributeRip" type="dm:RedistributeProtocol" minOccurs="0"/>
        <xs:element name="networkStatements" type="dm:NetworkStatements" minOccurs="0"/>
        <xs:element name="autoSummary" type="dm:ChangeableBoolean" minOccurs="0"/>
        <xs:element name="autonomousSystem" type="xs:unsignedInt"/>
        <xs:element name="maximumPaths" type="dm:ChangeableInteger" minOccurs="0"/>
        <xs:element name="logNeighbourChanges" type="dm:ChangeableBoolean" minOccurs="0"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

EigrpVrfAddressFamily is used in Eigrp which extends lib:Container. This indicates that these three elements can be added, deleted, and modified.

<xs:complexType name="Eigrp">
  <xs:complexContent>
    <xs:extension base="lib:Container">
      <xs:sequence>
        <xs:element name="asn" type="xs:int"/>
        <xs:element name="logNeighbourChanges" type="dm:ChangeableBoolean" minOccurs="0"/>
        <xs:element name="eigrpVrfAddressFamily" type="dm:EigrpVrfAddressFamily" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:extension>
  </xs:complexContent>
</xs:complexType>

Eigrp is used in eigrp where a key is defined.

<xs:element name="eigrp" type="dm:Eigrp" minOccurs="0">
  <xs:key name="eigrpVrfAddressFamilyKey">
    <xs:selector xpath="dm:eigrpVrfAddressFamily"/>
      <xs:field xpath="dm:vrfRef"/>
      <xs:field xpath="dm:vrfRdRef"/>
      <xs:field xpath="dm:autonomousSystem"/>
    </xs:key>
</xs:element>

Reading backwards, there is an element eigrp, which defines a key composed of three entities called vrfRef, vrfRdRef and autonomousSystem.

If the target and previously pushed device model have the same values for the three elements defined as keys and a change of any type was detected on the other children elements, then eigrp would be annotated with modify. The cartridge implementation would then send the appropriate eigrp command taking into account that this is a modify action.

If the target and previously pushed device model have different values for any of the three elements defined as keys and a change of any type was detected on the other child elements, then eigrp would be annotated with delete and add. The cartridge implementation would then send the appropriate eigrp command taking into account that a delete command must be sent followed by an add command.