Cisco Enhanced Device Interface Programmer's Guide, 2.0

Introduction

This section gives a brief overview of the features available in the Cisco Enhanced Device Interface (Cisco E-DI) XML Programmatic Interface (PI).

This chapter includes the following details:

•What Is A Programmatic Interface?

•What Is Cisco E-DI PI?

•Using Cisco E-DI With CatOS Devices

•Working Example

What Is A Programmatic Interface?

In a network management context, a PI is an interface for management applications to control and monitor networking devices. It is crafted specifically to meet the needs of network management applications. This is in contrast to a command line interface (CLI), which is intended and crafted for human operators.

The PI is a management interface that provides management applications with a set of common operations to control and monitor Cisco devices. A supporting data model described via XML and based on the network element's (NE's) command structure (hence sometimes referred to as the command model), allows users to configure the device. In order to accommodate users who want to continue making use of the command line interface (CLI) rather than the XML command model, the PI operations allow the transport of CLI commands and responses. These users have management applications using the XML-based data model and script-based tools using CLI.

What Is Cisco E-DI PI?

Cisco E-DI provides an XML PI based on NETCONF Configuration Protocol (draft-ietf-netconf-prot-05). The supported data model is published through XSD files. XSD representation of the data model is generated at the development time and is for a specific device type and OS combination.

The Cisco E-DI XML PI uses Telnet and SSH version1 or version 2 for transport.

Cisco E-DI PI is used for the following device level tasks:

•Configuring the device (also available through the CLI)

•Executing EXEC commands on the device (also available through the CLI)

The Cisco E-DI XML PI supports:

•Sessions Establishment

•Session Release

•Protocol operations/services.

•RPC messages based communication model for message exchange

•RPC message pipelining

•Various data stores during configuration e.g. running, startup

•Capabilities such as writable-running capability, candidate-configuration capability

•Sub-tree filtering

•The following protocol operations/services:

–<get-config>

–<edit-config>

–<copy-config>

–<delete-config

–<lock>

–<unlock>

–<get>

–<close-session>

–<kill-session>

–<commit>

–<discard-changes>

•Versioning of the data model

Note Management operations and data models will be backward compatible.

Using Cisco E-DI With CatOS Devices

Cisco Catalyst OS (CatOS) devices do not have a startup configuration. For consistency with Cisco IOS devices, Cisco E-DI allows the notion of a startup configuration for CatOS devices, and shows the running configuration as the startup configuration. Since both configurations are essentially the same, the following variations in the behavior of NETCONF operations occur:

•Locking the running configuration or startup configuration locks both running and startup configurations. Unlocking unlocks both running and startup configurations.

•Copying a running configuration into a startup configuration has no effect.

Using a Filter With CatOS Devices

In CLI mode, <get-config> and <get> permits filter specification using the <text-filter-spec> element:

•On Cisco IOS devices, this can take any values which are allowed on the device following the show running-config command.

•On CatOS devices, this can take any values allowed on the device following the show config command.

Working Example

This section provides a working example of the following hypothetical scenario:

1. Establish a Session

2. Get the Running Configuration

3. Edit Candidate Configuration

4. Get a Lock on Running Configuration

5. Commit the Changes

6. Close the Session

You will need to use the sample code provided by Cisco E-DI for a client program to achieve this. Once a session is established this scenario is realized by submitting the xml request text to an API method.

Establish a Session

There is no XML text from the client program required for this. There is XML involved during session establishment, but it is transparent to the user and is hidden by the API.

Get the Running Configuration

Get the running configuration as follows:

<nc:rpc message-id="1"

xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<nc:get-config>

<nc:source>

    <nc:running/>

</nc:source>

</nc:get-config>

</nc:rpc>

Edit Candidate Configuration

Add a user ciscotest1. The correct way of framing the request is learned from the XSD, in this case the XSD of a Cisco1700 family device for version 12.2(15)T14. This XSD will be made available to the users.

<rpc message-id="7" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<edit-config>

<target>

    <candidate/>

</target>

<default-operation>merge</default-operation>

<test-option>test-then-set</test-option>

<error-option>ignore-error</error-option>

<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">

    <cpi:xml-config-data 
xmlns:cpi="http://www.cisco.com/cpi_10/schema">

        <DeviceConfiguration 
xmlns="http://www.cisco.com/edi_20/Cisco1700/12.2(15)T14/1.2" 
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">

            <UserName>

                <Naming>

                    <UserName>ciscotest1</UserName>

                </Naming>

            </UserName>

        </DeviceConfiguration>

    </cpi:xml-config-data>

</config>

</edit-config>

</rpc>

Get a Lock on Running Configuration

In Cisco E-DI a candidate configuration is unique to a NETCONF session and is not shared. As such, a lock is always there implicitly on the candidate config store. When a commit is issued, the candidate config is written to the running configuration. While acquiring a lock is not mandatory, if a lock is needed, can be obtained as follows

<rpc message-id="3"

xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<lock>

<target>

    <running/>

</target>

</lock>

</rpc>

Commit the Changes

Commit the changes as follows:

<rpc message-id="4"

xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<commit/>

</rpc>

Close the Session

Close the session as follows:

<rpc message-id="5" 

xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<close-session/>

</rpc>

Note As a result of a close-session operation, the server releases all locks, therefore an explicit <unlock> is not necessary.