Cartridge Operations

4 Cartridge Operations

This chapter describes how cartridge resources are used to support cartridge operations.

Cartridge operations supported by XML configuration files include:

Audits: comparison of Oracle Communications IP Service Activator's internal representation of what is configured on a device, and the actual device configuration. An audit template file is used to configure the audit and its report. Audit synonyms are used to identify commands that are logically equivalent.
Options: allows for variation in command syntax by certain device type and OS combinations within device families.
Capabilities: indicates what supported capabilities should be reported back to the IP Service Activator policy server when a device supported by a cartridge is discovered.
Message Definition: patterns defining responses from the device
Pre- and Post-Checks: provide the ability verify information on a device when the annotated DM to CLI transform executes, before the general configuration is sent.
Cartridge Version: The cartridge version is used as the version of the device model that the cartridge generates. If you make significant modifications which include device model schema changes to a cartridge that is already deployed, you will need to upgrade the device model.

In addition, the SDK supports the configuration of cartridges to enable the use of services from the Configuration Management product.

Audits

Audits identify discrepancies between IP Service Activator's representation of a device's configuration and the actual configuration currently on the device. For an in depth analysis of the configuration running on a device, an IP Service Activator user can perform a device audit or a per-service audit. You define auditTemplates and audit synonyms that tailor the audit report output.

Audit Template

Audit templates define filter patterns to be applied to commands to identify configuration of interest, and to affect their inclusion in the audit report, and to set attributes on the command results, which, when viewed using a stylesheet will affect how they are displayed to the IP Service Activator user.

Commands to show configuration, and commands to logout, and all commands that can be applied to the device by the cartridge should be listed. All commands that can be applied to the device by a service cartridge should be listed.

Note:

For a service cartridge, do not include commands to show configuration and commands to logout; such commands should be listed in the audit template file for the base cartridge that this service cartridge extends.

Audit templates for base cartridges have two command sets:

First command set: the device commands to list a device's entire configuration
Second command set: a complete set of the commands that the cartridge is capable of sending to the device

Audit templates for service cartridges have only the second command set.

For a service cartridge, the first command set is not needed; the first command set from the base cartridge's audit template file describes the commands that the Network Processor must issue to the device to retrieve the device's entire configuration for the base cartridge, and all of the service cartridges that extend the services of the base cartridge.

A sample auditTemplate.xml file follows:

<commandSession xsi:schemaLocation="http://www.metasolv.com/serviceactivator/climodel  file:../../../../networkprocessor/climodel/cliModel.xsd" xmlns="http://www.metasolv.com/serviceactivator/climodel" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <command>
    <!--commands to show configuration-->
    <commandId>show-commands</commandId>
    <commandString/>
    <command>
      <commandId>show-commands.terminal_length_0</commandId>
      <commandString>terminal length 0</commandString>
    </command>
    <command kind="show">
      <commandId>show-commands.show_running-config</commandId>
      <commandString>show running-config</commandString>
      <conditionalPrompt>.*(?m)^end$.*</conditionalPrompt>
    </command>
    <command>
      <commandId>show-commands.logout</commandId>
      <commandString>logout</commandString>
      <conditionalPrompt>.*</conditionalPrompt>
    </command>
  </command>
  <command>
    <!--context specific filter patterns to identify configuration of interest-->
    <commandId>cisco</commandId>
    <commandString/>
    <command kind="ALWAYSIGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^Building configuration.*</commandString>
    </command>
    <command kind="ALWAYSIGNORE">
      <commandId>^ignore^</commandId>
      <commandString>Current configuration.*</commandString>
    </command>
    <command kind="ALWAYSIGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^exit$</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^terminal length 0$</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^show .*</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^conf t$</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^end$</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^copy</commandString>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^logout$</commandString>
    </command>
    <command>
      <commandId>cisco.vlan</commandId>
      <commandString>^vlan \d+$</commandString>
      <command kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^$</commandString>
      </command>
    </command>
    <command kind="IGNORE">
      <commandId>^ignore^</commandId>
      <commandString>^default interface .*$</commandString>
    </command>
    <command>
      <commandId>cisco.interface</commandId>
      <commandString>^interface</commandString>
      <command>
        <commandId>cisco.interface.description</commandId>
        <commandString>^description .*$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.mtu</commandId>
        <commandString>^mtu \d+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.ip_address</commandId>
        <commandString>^(no\s)?ip address</commandString>
      </command>
      <command>
        <commandId>cisco.interface.shutdown</commandId>
        <commandString>^shutdown$</commandString>
    </command>
      <command kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^no shutdown$</commandString>
      </command>
      <command kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^no logging event bundle-status$</commandString>
      </command>
      <command kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^no logging event trunk-status$</commandString>
      </command>
      <command kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^no logging event link-status$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.logging_event_bundle-status</commandId>
        <commandString>^logging event bundle-status$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.logging_event_trunk-status</commandId>
        <commandString>^logging event trunk-status$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.logging_event_link-status</commandId>
        <commandString>^logging event link-status$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.mls_qos_trust</commandId>
        <commandString>^mls qos trust \w*$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport</commandId>
        <commandString>^switchport$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_trunk_encapsulation</commandId>
        <commandString>^switchport trunk encapsulation \w+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_trunk_allowed_vlan</commandId>
        <commandString>^switchport trunk allowed vlan</commandString>
      </command>
      <coommand kind="IGNORE">
        <commandId>^ignore^</commandId>
        <commandString>^switchport access vlan 1$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_access_vlan</commandId>
        <commandString>^switchport access vlan \d+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_mode</commandId>
        <commandString>^switchport mode \w+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_port-security</commandId>
        <commandString>^switchport port-security$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_port-security_maximum</commandId>
        <commandString>^switchport port-security maximum \d+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_port-security_violation</commandId>
        <commandString>^switchport port-security violation \w+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_port-security_mac-address_sticky</commandId>
        <commandString>^switchport port-security mac-address sticky$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.switchport_nonegotiate</commandId>
        <commandString>^switchport nonegotiate.*$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.spanning-tree_portfast</commandId>
        <commandString>^spanning-tree portfast.*$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.spanning-tree_bpduguard</commandId>
        <commandString>^spanning-tree bpduguard.*$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.duplex</commandId>
        <commandString>^duplex \w+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.speed</commandId>
        <commandString>^speed \w+$</commandString>
      </command>
      <command>
        <commandId>cisco.interface.media-type</commandId>
        <commandString>^media-type \S+$</commandString>
      </command>
    </command>
    <!--Alias command for configuration version -->
    <command configVersion="true" reportManualConfig="true">
      <commandId>cisco.alias_IpsaConfigVersion</commandId>
      <commandString>^alias exec IpsaConfigVersion \S+</commandString>
    </command>
  </command>
</commandSession>

In the above auditTemplate.xml sample, the section under the comment  contains the commands to retrieve the device's current configuration.

The section under the comment  identifies all the commands the cartridge is capable of sending to the device.

When you populate the auditTemplate.xml file as part of the cartridge development process, you must specify every command you intend to support, otherwise the audit function will not work correctly.

When an audit is requested for the device, the Network Processor sends the first command set to the device to retrieve its configuration, which is filtered against the commands in the second command set. Commands that match those configured by the cartridge (i.e. listed in the second command set) are converted into a CLI document.

The Network Processor then invokes the annotated device model to CLI transform from the cartridge on the last pushed (i.e. persisted) device model (which matches IP Service Activator's internal representation of what is configured on the device).

A comparison is made between the two CLI documents. This comparison can highlight discrepancies including:

Commands sent to the device that are now missing
Commands added to the device that are not in the Network Processor device model (i.e. manually configured outside of IP Service Activator)
Commands that are in the wrong order on the device. (In some cases command ordering affects how the device works.)

Audit Template Command Attributes

Audit template attributes are used to accommodate variations in device responses and to customize the audit report. You can apply these attributes to each individual command element to tell the audit to treat this command in a particular manner.

For example, when you read device configuration, the device could:

display a command in lower case where IP Service Activator provisioned the device in upper case
display commands indented incorrectly (resulting in wrong context interpretation)

Attributes can be used to ensure the expected command format is displayed in the audit report.

You can use attributes to indicate that specific commands need to follow one another in a particular order.

The command attributes are:

kind=string
configVersion=boolean
ordered=string
autoIndentUtil=string
ignoreCase=string
reportManualConfig=boolean
brokenIndentRulesOffset=integer

kind=string

The kind attribute affects how the command is used to match commands on the device. Table 4-1 lists the possible string values.

Table 4-1 Value Strings for Kind Attribute

Value	Effect
ALWAYSIGNORE	Excludes the command from the audit report when found in any context.
IGNORE	Excludes the command from the audit report when found in this context.
IGNORE_CASE	Performs a case insensitive comparison with the command on the device.
IGNORE_CHARS	Performs a comparison with commands on the device, ignoring characters that follow the attribute (e.g. <command kind="IGNORE_CHARS -">). A dash (-) appears in the device configuration, however, you want the audit to ignore it.
CHECK_DEFAULT	Performs a comparison with commands on the device marking missing commands as “potentially" missing. This is used for special handling in cases where devices don't display default values in a command string.
PARTIAL	Performs a comparison with commands on the device taking the command element name (as depicted in the audit template) as part of the full command. This allows the audit to determine equality between IP Service Activator provisioned commands and those seen on the device using a partial comparison only.

Table 4-2 shows how the audit template command kind attribute affects the inclusion of the command, and its kind attribute value in the resulting audit report.

Table 4-2 Effect of Kind Attribute on Audit Report

#	Cmd in IP Service Activator	Cmd on Device	Command in Audit Template	Kind in Resulting Audit Report for showAll=false (IPSA)	Kind in Resulting Audit Report for showAll=true (CM)
1.	C1	C1	Present	NORMAL	--
2.	C1	C1	Present + kind=CHECK_DEFAULT	NORMAL	--
3.	C1	C1	Present + kind=IGNORE	exclude	UNMANAGED
4.	C1	C1	Not Present	exclude	NORMAL
5.	C1	C1'	Present \| Present + kind=PARTIAL	CHANGED	CHANGED (Missing: Conflickt)
6.	C1	C1'	Present + kind=PARTIAL_DISPLAY_ALL	MISSING	CHANGED (Missing: Conflict)
7.	C1	C1'	Present + kind="CHECK_DEFAULT"	CHANGED	CHANGED (Potential: Conflict)
8.	C1	C1'	Present + kind="IGNORE"	exclude	UNMANAGED
9.	C1	C1'	Not Present	exclude	CHANGED (Missing: Conflict)
10.	C1	missing	Present	MISSING	--
11.	C1	missing	Present + kind="CHECK_DEFAULT"	POTENTIAL	--
12.	C1	missing	Present + kind="IGNORE"	exclude	exclude
13.	C1	missing	Not Present	exclude	MISSING
14.	--	C1	Present	CONFLICT	--
15.	--	C1	Present + kind="CHECK_DEFAULT"	POTENTIAL	--
16.	--	C1	Present + kind="IGNORE"	exclude	UNMANAGED
17.	--	C1	Not Present	exclude	UNMANAGED

Note:

In Table 4-2:

C1' means the command is the same, but some of its arguments are different.
CHANGED is a JuniperXML only tag; for others, this will show up as a MISSING:CONFLICT pair

configVersion=boolean

Set configVersion to true on the command that sets the IP Service Activator configuration version. The IP Service Activator configuration version is a timestamp of when the configuration was last modified by IP Service Activator.

ordered=string

The ordered attribute lets you control whether or not the sequencing of commands is relevant when determining whether or not discrepancies exist between the device and the IP Service Activator device model. Define a string value, and set the ordered attribute value to the same string value for all commands at the same nesting level for which the sequencing is relevant. The correct sequence of the commands will be the order they appear in the audit template.

For example, to specify that if commands "cmd B", and "cmd D" both appear under command "cmd X", then "cmd D" must appear after "cmd B", set ordered="OrderBD" for both "cmd B", and "cmd D".

In this case, no discrepancies will be found since B, and D appear in the correct sequence relative to each other:

cmd X
  cmd A
  cmd B
  cmd C
  cmd D
  cmd E

In this case, discrepancies will be found since B, and D do not appear in the correct sequence relative to each other:

cmd X
  cmd D
  cmd A
  cmd B
  cmd C
  cmd E

autoIndentUntil=string

The autoIntendUntil attribute tells the audit that every command under the current command is a child command until string is detected, then context of the current command will be exited. This attribute is used to deal with bad indenting problems.

For example, to tell the audit that commands B and C are children of command A, despite bad indenting:

autoIndentUntil="cmd D"
cmd A
cmd B
cmd C
cmd D

ignoreCase=string

Performs a case insensitive comparison with the command on the device.

reportManualConfig=boolean

The reportManualConfig attribute lets you explicitly control whether a command can be reported as a manual configuration. By default, global commands are not reported as manual configurations, but nested commands are.

brokenIndentRulesOffset=integer

The brokenIndentRulesOffset attribute tells the audit that this command has a bad indent and that it should be corrected to an absolute value. This attribute is used to deal with bad indenting problems and comes into play with when CLIParser will prematurely break out of context.

For example, use brokenIndentRulesOffset="2" for command D in the following list:

cmd A
  cmd B
  cmd C
  cmd D
  cmd E

In the above example, command D is suppose to be a child of command A but its relative position shows it is out of context for command A. The brokenIndentRulesOffset attribute will come into play when audit interrogates command D and is about break out of command A context. The absolute position of command D will be reset to ensure that it is seen as a child of command A or peer to commands C and E.

Audit Synonyms

Some device IOS combinations display commands differently from the manner in which the commands were activated on the device. This can cause an audit to fail even though the commands reported are actually logically equivalent to those that were configured.

The cartridge architecture allows you to specify synonyms for commands on the target device. Synonyms use regular expressions to match and replace commands, so it can be determined if two commands are equivalent.

You can specify system synonyms on a per-cartridge basis. The discussion of audit synonyms in IP Service Activator System Administrator's Guide describes how audit synonyms work, and describes how an administrator can specify custom synonyms to create new synonyms or redefine system synonyms after IP Service Activator is deployed.

You can specify system synonyms in the synonyms.xml file included in the cartridge. The samples and descriptions of elements in a synonyms file, as described in IP Service Activator System Administrator's Guide, can be used as reference material for an administrator editing the content of a custom synonyms file or a cartridge developer editing the content of a system synonyms file.

Synonyms can be specified for both the expected command and for the configured command.

Note:

A given command can only have one synonym made up of one or more match and replace criteria. For example, A can be equivalent to A' but not A" simultaneously for equivalence testing within the scope of a single auditTemplate.

For further details on audit synonyms, refer to IP Service Activator System Administrator's Guide.

Options

There can be variations in the command syntax for certain commands within device families based on the specific device type and OS variant. Options allow you to specify the correct commands to handle these variants, without having to create a separate service cartridge.

Options allow you to set information in the device model which will render the correct syntax version for a given command.

To do this, you define and document configuration options for a cartridge, and implement the variations in the service model to device model transform, and the annotated device model to CLI transform, based on option values.

Option values for specific device type and IOS combinations are specified in option configuration files, which are registered by cartridge units in the appropriate registry entry file. The option configuration files, and the registry entries that reference them, may be customized by the system administrator once the cartridge is deployed.

For complete details on creating options for a cartridge, refer to IP Service Activator SDK Base Cartridge Developer Guide.

Capabilities

In IP Service Activator, when a device is discovered, the policy server fetches the device's capabilities from the Network Processor, so it can model the device appropriately for the user. The Network Processor returns capabilities based on the base and service cartridges that manage that device.

It is the capabilities files that specify the ability of the device and cartridge to support different types of policies at the device, interface and sub-interface level.

Capabilities for different service cartridges are ORed together to provide a single view of the overall device capabilities to the policy server. A fault is generated if different service cartridges specify conflicting capabilities.

It is very important when you are creating cartridges for use with IP Service Activator that the capabilities files be appropriately configured to report the capabilities you are providing policy and service support for.

A sample capabilities file follows:

<caps:capabilities
  xmlns:caps="http://www.metasolv.com/serviceactivator/capabilities"
  xmlns="http://www.metasolv.com/serviceactivator/capabilities"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.metasolv.com/serviceactivator/capabilities">
  <caps:device>
  </caps:device>
  <caps:interface>
    <caps:ifType>32</caps:ifType>
    <caps:inbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:ip_unnumbered_support>0</caps:ip_unnumbered_support>
    </caps:inbound>
    <caps:outbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:vce_support>
        <caps:supports_virtual_ce>1</caps:supports_virtual_ce>
        <caps:supports_RIP_virtual_ce>1</caps:supports_RIP_virtual_ce>
        <caps:supports_static_virtual_ce>1</caps:supports_static_virtual_ce>
        <caps:supports_OSPF_virtual_ce>0</caps:supports_OSPF_virtual_ce>
        <caps:supports_eBGP_virtual_ce>1</caps:supports_eBGP_virtual_ce>
        <caps:supports_EIGRP_virtual_ce>1</caps:supports_EIGRP_virtual_ce>				
      </caps:vce_support>
      <caps:ip_unnumbered_support>0</caps:ip_unnumbered_support>
    </caps:outbound>
    <caps:subInterface>
      <caps:inbound>
        <caps:access_rule_support>
          <caps:access_rules_supported>255</caps:access_rules_supported>
          <caps:classification_supported>
            <caps:supported>SRC_IP</caps:supported>
            <caps:supported>DST_IP</caps:supported>
            <caps:supported>SRC_PORT</caps:supported>
            <caps:supported>DST_PORT</caps:supported>
            <caps:supported>IP_PROTO</caps:supported>
            <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
            <caps:supported>TCP_ESTABLISHED</caps:supported>
          </caps:classification_supported>
        </caps:access_rule_support>
        <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
      </caps:inbound>
      <caps:outbound>
        <caps:access_rule_support>
          <caps:access_rules_supported>255</caps:access_rules_supported>
          <caps:classification_supported>
            <caps:supported>SRC_IP</caps:supported>
            <caps:supported>DST_IP</caps:supported>
            <caps:supported>SRC_PORT</caps:supported>
            <caps:supported>DST_PORT</caps:supported>
            <caps:supported>IP_PROTO</caps:supported>
            <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
            <caps:supported>TCP_ESTABLISHED</caps:supported>
          </caps:classification_supported>
        </caps:access_rule_support>
        <caps:vce_support>
          <caps:supports_virtual_ce>1</caps:supports_virtual_ce>
          <caps:supports_RIP_virtual_ce>1</caps:supports_RIP_virtual_ce>
          <caps:supports_static_virtual_ce>1</caps:supports_static_virtual_ce>
          <caps:supports_OSPF_virtual_ce>0</caps:supports_OSPF_virtual_ce>
          <caps:supports_eBGP_virtual_ce>1</caps:supports_eBGP_virtual_ce>
          <caps:supports_EIGRP_virtual_ce>1</caps:supports_EIGRP_virtual_ce>				
        </caps:vce_support>
        <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
    </caps:outbound>
    </caps:subInterface>
  </caps:interface>
  <caps:interface>
    <caps:ifType>23</caps:ifType>
    <caps:inbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
    </caps:inbound>
    <caps:outbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:vce_support>
        <caps:supports_virtual_ce>1</caps:supports_virtual_ce>
        <caps:supports_RIP_virtual_ce>1</caps:supports_RIP_virtual_ce>
        <caps:supports_static_virtual_ce>1</caps:supports_static_virtual_ce>
        <caps:supports_OSPF_virtual_ce>0</caps:supports_OSPF_virtual_ce>
        <caps:supports_eBGP_virtual_ce>1</caps:supports_eBGP_virtual_ce>
        <caps:supports_EIGRP_virtual_ce>1</caps:supports_EIGRP_virtual_ce>				
      </caps:vce_support>
      <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
    </caps:outbound>
  </caps:interface>
  <caps:interface>
    <caps:ifType>22</caps:ifType>
    <caps:inbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
    </caps:inbound>
    <caps:outbound>
      <caps:access_rule_support>
        <caps:access_rules_supported>255</caps:access_rules_supported>
        <caps:classification_supported>
          <caps:supported>SRC_IP</caps:supported>
          <caps:supported>DST_IP</caps:supported>
          <caps:supported>SRC_PORT</caps:supported>
          <caps:supported>DST_PORT</caps:supported>
          <caps:supported>IP_PROTO</caps:supported>
          <caps:supported>TCP_HEADER_OPTIONS</caps:supported>
          <caps:supported>TCP_ESTABLISHED</caps:supported>
        </caps:classification_supported>
      </caps:access_rule_support>
      <caps:vce_support>
        <caps:supports_virtual_ce>1</caps:supports_virtual_ce>
        <caps:supports_RIP_virtual_ce>1</caps:supports_RIP_virtual_ce>
        <caps:supports_static_virtual_ce>1</caps:supports_static_virtual_ce>
        <caps:supports_OSPF_virtual_ce>0</caps:supports_OSPF_virtual_ce>
        <caps:supports_eBGP_virtual_ce>1</caps:supports_eBGP_virtual_ce>
        <caps:supports_EIGRP_virtual_ce>1</caps:supports_EIGRP_virtual_ce>				
      </caps:vce_support>
      <caps:ip_unnumbered_support>1</caps:ip_unnumbered_support>
    </caps:outbound>
  </caps:interface>
</caps:capabilities>

The relevant sections are:

Device: specifies device capabilities
Interface
- ifType: specifies interface capabilities for the interface type instance

By default, capabilities are set to false (i.e. 0) meaning the capability is not supported. Specifying true (i.e. 1) indicates that the service is supported. In some cases, support is specified using strings which indicate which aspect of a capability is supported. For example, the number of access rules supported on an interface of type 32:

				<caps:access_rules_supported>255</caps:access_rules_supported>

In the sample above, there are no device-level capabilities. If a device for which this capabilities file applies was discovered, and had an interface of type 32, then that interface would have support for the capabilities marked true (1).

Message Definition

Success, warning and error message pattern files can be defined for service cartridges in the same way as for base cartridges. For example, device responses for commands sent by a service cartridge are analyzed and patterns are created in the message pattern files for that service cartridge. The difference is that for a base cartridge, the messages files are referenced from the Registry.xml file, and for a service cartridge, the messages files are referenced from the Extension.xml file.

The Network Processor compares device responses against sets of patterns stored in XML files to monitor its interactions with the device. By finding matches with stored messages patterns, the Network Processor can determine the results of commands sent to the device.

The Network Processor changes existing configuration on the device only if the device response matches a success pattern, a non-blocking warning pattern, or if there is no response at all (i.e. only the command prompt is returned).

As the Network Processor generates the needed commands, connects to the device, and starts changing the device configuration, the responses from the device are analyzed after each command. The following categories of responses are defined:

Success: if the device response matches a success pattern or there is no response at all (i.e. only a prompt is returned) then the command is considered to be successful.
Warning (blocking and non-blocking): if the response from the device matches a non-blocking warning pattern, a fault (i.e. Warning) is raised. If the response from the device matches a blocking warning pattern, a fault is raised, and all concretes affected by that transaction are rejected and the partially implemented configuration is rolled back.
Error: if the response from the device matches one of the known error patterns, then a fault (i.e. Error) is raised against the device itself, all the concretes affected by that transaction are rejected and the partially implemented configuration is rolled back.

In addition, if the response from the device does not match any success, warning, or error pattern, then the response is considered to be an unknown error. A fault (i.e. Error) is raised against the device, all the concretes affected by that transaction are rejected, and the partially implemented configuration is rolled back. The fault message includes the rejected command and the actual message returned by the device. Note that successive white space and new line characters are removed from the device response. The configuration conflict is recorded in the audit log file, and the device state is marked Intervention Required for decision/action by the system administrator.

Overriding Message Definitions

Once the cartridge is deployed, the list of success patterns can be overridden by the system administrator. For this purpose, the cartridge .zip file includes a copy of the successMessages.xml file in the vendor specific sampleRegistry directory. For example, for a Cisco cartridge, the path would be Service_Activator_home\Config\networkProcessor\ciscoSampleRegistry\messages\successMessages.xml.

To override the success patterns, a system administrator can edit a copy of the successMessage.xml file and copy it to the same relative location referenced by the appropriate registry entry. If no successMessages.xml file is specified in the registry file entry, the global SuccessMessages.xml file will be used.

Note:

The global SuccessMessages.xml file is deprecated.

For example, to override the Cisco successMessages.xml file once the cartridge has been deployed:

Copy the successMessages.xml file found in the install directory at

Service_Activator_home\Config\networkProcessor\ciscoSampleRegistry\messages\successMessages.xml

to

Service_Activator_home\Config\networkProcessor\com\metasolv\serviceactivator\cartridges\cisco\successMessages.xml
Add, modify, or delete success patterns as necessary.
Ensure that the location specified in the appropriate registry file reflects the actual location of the file relative to the install directory at Service_Activator_home\Config\networkProcessor

For example:
```
<successMessages>com\metasolv\serviceactivator\cartridges\cisco\messages\successMessages.xml</successMessages>
```

The same process can be applied for warning and error message files.

For details on message files as part of a base cartridge, refer to IP Service Activator SDK Base Cartridge Developer Guide.

Pre- and Post-Checks

Pre- and post-checks provide the ability verify information on a device when the annotated DM to CLI transform executes, before the general configuration is sent. This allows you to confirm that prerequisites to the configuration are met. For example, some configuration may rely on certain other values being configured on the device. Alternatively, some configuration may conflict with certain values that may be configured on the device.

After configuration is sent, you have the opportunity to have a post-check invoked to verify some aspect of the commands that were sent to the device.

Types of Pre- and Post-Checks

There are two basic types of checks: Type I and Type II.

For Type I checks, the framework handles the pass/fail decision, based on regular expression pattern matching of the result against the message files.

With Type II checks, the result of sending the check commands are passed back, and then programmatically inspected using a customized XQuery. Appropriate action is taken based on that result.

Type I Checks

In a Type I check, the check mechanism sends commands to the device, and then parses the results against the cartridges message files. If a match occurs, an appropriate action is taken to continue or abort the remaining configuration.

Type I check is imbedded in the CLI document executed by the Network Processor to send the CLI to the device.

Type II Checks

A Type II check is executed before the CLI document is executed by the Network Processor. The check mechanism sends commands to the device, and returns the result. This result is programmatically inspected based on your customized XQuery to determine whether to continue or abort the remaining configuration.

There are two types of Type II checks:

Type IIa checks: uses a success/error pattern. The pattern match determines how the pass/fail condition is met.
Type IIb checks: the command instance has no success/error pattern. The results are inspected using your customized XQuery to determine what action to take.

Cartridge Version

The cartridge version is used as the version of the device model that the cartridge generates. It is set in the cartridge skeleton properties file (sdk_global_cartridgeVersion) and the value of it is put into the dm-version.xq file when it is generated. Any device model that is generated by the cartridge is given this version number.

A sample fragment from dm-version.xq follows: ""

declare variable $dmver:version := "2.0";

The version format can be a, a.b, a.b.c (major, major.minor, major.minor.sub-minor), where a, b, c must all be numeric.

As a cartridge developer, you want to increment the cartridge version whenever a significant change to the device model has occurred which requires a non-trivial upgrade to an existing DM.

Device Model Upgrades

If you make modifications which include device model schema changes to a cartridge that is already deployed, you must be aware of the effect of these changes on your IP Service Activator installation, in particular, persistent data.

As the cartridge developer, you are responsible for analyzing whether or not a device model upgrade is required, and if so:

Updating the cartridge version
Updating and unit testing the upgrade source code related to the modified device model

Once the cartridge is deployed, non-trivial changes to devicemodel.xsd will require a device model upgrade and may or may not require a custom transform for the upgrade.

Examples of non-trivial device model changes are:

Introduction of mandatory attributes
Removal of attributes
Substantial modification of an existing attribute
Re-ordering of attributes

An example of a trivial device model change is:

Introduction of optional attributes

The device model transform is required if the change made to the schema impacts the use of the last device model during the service model to device model transform. By default, the last device model is not used in the generated cartridge source files. It would only be used by custom XQuery code. If it is not used, then the upgrade will regenerate the new version of the last device model without the need for a custom upgrade transform.

Should you make a non-trivial change to a device model, then you must write a transform that allows the Network Processor upgrade tool (NpUpgrade) to upgrade the existing device model.

Network Processor NpUpgrade

The NpUpgrade does a partial upgrade of all device models, including those for the service cartridges. It looks for the xquerylib\DmUpgrade.xq in the same classpath as sm2dm.xq, and if this file exists, it uses the XQuery to perform the upgrade. The upgraded device model is used as the last device model in the upgrade process.

An editable DmUpgrade.xq is added to the xquerylib directory for each base and service cartridge upon source file generation.
For each cartridge, an SDK_home\...\test\models\upgradeFrom\sampleDeviceModel.xml file is provided for testing purposes.
A test file, SDK_home\...\test\DmUpgradeTests.java, is provided to transform the sample device model by running the DmUpgrade.xq xquery.

Configuration Version

The IpsaConfigVersion is removed from a device when the last concrete is removed from the device in IP Service Activator. Typically, this coincides with the removal of the last IP Service Activator configured command from the device.

An exception to this occurs when a configuration policy, which does not generate commands, is the last configuration to be removed from the device in IP Service Activator. For example, schedule is an example of a configuration policy that does not generate commands. If IP Service Activator is running with Configuration Management, and you have installed a schedule on a device, along with other concretes which do generate commands, the device will maintain an IpsaConfigVersion, until all configuration is removed including the schedule.

Configuration Management Support

The SDK supports the configuration of cartridges to enable the use of services from the Configuration Management product.

The following services provided by Configuration Management can be supported in the Network Processor:

Audit: supported through base and service cartridges
Configuration activation: supported from configuration policies through service cartridges in conjunction with a base cartridge.
Restore: can be implemented in base cartridges

For More Information on Cartridge Operations

For extensive information on the following points, see IP Service Activator System Administrator's Guide:

Audit types and reports
The syntax of audit template file entries
Running a device audit
Contents of synonyms files
Tools to help create synonyms

For information on configuring cartridges to support the use of services from the Configuration Management product, see IP Service Activator SDK Configuration Management Developer Guide.