Chapter 4 - Cisco CRS-1 Series XML and Native Data Operations

Table Of Contents

Cisco CRS-1 Series XML and Native Data Operations

Native Data Operation Content

Request Type Tag and Namespaces

Object Hierarchy

Dependencies Between Configuration Items

Null Value Representations

Operation Triggering

Native Data Operation Examples

Cisco CRS-1 Series XML and Native Data Operations

Native data operations <Get>, <Set>, and <Delete> provide basic access to configuration and operational data residing on the Cisco CRS-1 Series Carrier Routing System (Cisco CRS-1 Series) router.

This chapter describes the content of the native data operations and provides an example of each operation type.

Note The XML application programming interface (API) code is available for use on any Cisco platform that runs Cisco IOS XR software.

Native Data Operation Content

The content of native data operations includes the request type and relevant object class hierarchy as described in the following sections.

The operations are described in the following sections:

• Request Type Tag and Namespaces

• Object Hierarchy

• Dependencies Between Configuration Items

• Null Value Representations

• Operation Triggering

• Native Data Operation Examples

The following example shows a native data operation request:

Sample XML Client Native Data Operation Request

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Operation>
    <Request Type>
      .
      .
      .
        object hierarchy goes here
      .
      .
      .
    </Request Type>
  </Operation>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Operation>
    <Request Type>
      .
      .
      .
        response content returned here
      .
      .
      .
    </Request Type>
  </Operation>
</Response>
Request Type Tag and Namespaces

The request type tag must follow the operation type tag within a native data operation request.

Table 4-1 describes the type of the request that must be specified as applying to one of the namespaces.

Table 4-1 Namespace Descriptions

Namespace

Description

<Configuration>

Provides access to the router configuration data analogous to command-line interface (CLI) configuration commands. The allowed operations on configuration data are <Get>, <Set>, and <Delete>.

<Operational>

Provides access to the router operational data and is analogous to CLI show commands. The only operation allowed on operational data is <Get>.

<Action>

Provides access to the action data, for example, the clear commands. The only allowed operation on action data is <Set>.

<AdminOperational>

Provides access to the router administration operational data. The only operation allowed on administration operational data is <Get>.

<AdminAction>

Provides access to the router administration action data, for example, the clear commands. The only allowed operation on administration action data is <Set>.

Object Hierarchy

A hierarchy of elements is included to specify the items to get, set, or delete, and so on, after the request type tag is specified. The precise hierarchy is defined by the Cisco CRS-1 Series XML component schemas.

Note You should use only the supported XML schema objects; therefore, do not attempt to write a request for other objects.

The Cisco CRS-1 Series XML schema information is mapped to the XML instance.

Main Hierarchy Structure

The main structure of the hierarchy consists of the native data model organized as a tree of nodes, where related data items appear in the same branch of the tree. At each level of the tree, a node is a container of further, more specific sets of related data, or a leaf that holds an actual value.

For example, the first element in the configuration data model is <Configuration>, which contains all possible configuration items. The children of this element are more specific groups of configuration, such as <BGP> for Border Gateway Protocol (BGP) configuration, and <ISIS> for Intermediate System-to-Intermediate System (ISIS) configuration. Beneath the <BGP> element the data is further compartmentalized with the <Global> element for global BGP configuration and <BGPEntity> element for per-entity BGP configuration. This compartmentalization continues down to the elements that hold the values, the values being the character data of the element.

The following example shows the main hierarchy structure:

<Configuration>
  <BGP>
    .
    .
    .
    <Global>
    .
    .
    .
        <DefaultMetric>10</DefaultMetric>
    .
    .
    .
    </Global>
    <BGPEntity>
    .
    .
    .
    </BGPEntity>
    .
    .
    .
  </BGP>
  <ISIS>
        .
    .
    .
  </ISIS>
</Configuration>

Data can be retrieved at any level in the hierarchy—one particular data item can be examined, or all of the data items in a branch of the tree can be returned in one request (see Chapter 5, "Cisco CRS-1 Series XML and Native Data Access Techniques," for details on how to do perform hierarchical data retrieval).

Similarly, configuration data can be deleted at any granularity—one item can be deleted, or a whole branch of related configuration can be deleted. So, for example, all BGP configuration can be deleted in one request, or just the value of the default metric.

Hierarchy Tables

One special type of container element is a table. Tables can hold any number of keyed entries, and are used when there can be multiple instances of an entity. For example, BGP has a table of multiple neighbors, each of which has a unique IP address "key" to identify it. In this case, the table element is <NeighborTable>, and its child element signifying a particular neighbor is <Neighbor>. To specify the key, an extension to the basic parent-child hierarchy is used, where a <Naming> element appears under the child element, containing the key to the table entry.

The following example shows hierarchy tables:

<Configuration>
  <BGP>
    .
    .
    .
    <BGPEntity>
      <NeighborTable>
        <Neighbor>
          <Naming>
            <IPAddress>
              <IPV4Address>10.0.101.6</IPV4Address>
            </IPAddress>
          </Naming>
          <RemoteAS>6</RemoteAS>
        </Neighbor>
        <Neighbor>
          <Naming>
            <IPAddress>
              <IPV4Address>10.0.101.7</IPV4Address>
            </IPAddress>
          </Naming>
          <RemoteAS>7</RemoteAS>
        </Neighbor>
      </NeighborTable>
    </BGPEntity>
    .
    .
    .
  </BGP>
  <ISIS>
    .
    .
    .
  </ISIS>
</Configuration>

Use tables to access a specific data item for an entry (for example, getting the remote autonomous system number for neighbor 10.0.101.6), or all data for an entry, or even all data for all entries.

Tables also provide the extra feature of allowing the list of entries in the table to be returned. See the "XML Request Using Operation Scope (Content Attribute)" section on page 5-74 in Chapter 5, "Cisco CRS-1 Series XML and Native Data Access Techniques."

Returned entries from tables can be used to show all neighbors configured, for example, without showing all of their data.

Tables in the operational data model often have a further feature when retrieving their entries. The tables can be filtered on particular criteria to return just the set of entries that fulfill those criteria. For instance, the table of BGP neighbors can be filtered on address family or autonomous system number or update group, or all three. To apply a filter to a table, use another extension to the basic parent-child hierarchy, where a <Filter> element appears under the table element, containing the criteria to filter on.

The following example shows table filtering:

<Operational>
  <BGP>
    <NeighborTable>
      <Filter>
        <BGP_AFFilter>
          <AF>IPv4Unicast</AF>
        </BGP_AFFilter>
      </Filter>
    </NeighborTable>
  </BGP>
</Operational>
Leaf Nodes

The leaf nodes hold values and are generally simple one-value items where the element representing the leaf node uses character data to specify the value (as in "<DefaultMetric>10</DefaultMetric>" in the example in the "Main Hierarchy Structure" section. In some cases there may be more than one value to specify—for example, when you configure the administrative distance for an address family (the <Distance> element), three values must be given together. Specifying more than one value is achieved by adding further child elements to the leaf, each of which indicates the particular value being configured.

The following example shows leaf nodes:

<Configuration>
  <BGP>
    .
    .
    .
      <Distance>
        <ExternalRoutes>20</ExternalRoutes>
        <InternalRoutes>250</InternalRoutes>
        <LocalRoutes>200</LocalRoutes>
      </Distance>
    .
    .
    .
  </BGP>
</Configuration>

Sometimes there may be even more structure to the values (with additional levels in the hierarchy beneath the <Distance> tag as a means for grouping the related parts of the data together), although they are still only "setable" or "getable" as one entity. The extreme example of this is that in some of the information returned from the operational data model, all of the values pertaining to the status of a particular object may be grouped as one leaf. For example, a request to retrieve a particular BGP path status returns all the values associated with that path.

Dependencies Between Configuration Items

Dependencies between configuration items are not articulated in the XML schema nor are they enforced by the XML infrastructure; for example, if item A is this value, then item B must be one of these values, and so forth. The back-end Cisco CRS-1 Series operating system applications are responsible for preventing inconsistent configuration from being set. In addition, the management agents are responsible for carrying out the appropriate operations on dependent configuration items through the XML interface.

Null Value Representations

The standard attribute "xsi:nil" is used with a value of "true" when a null value is specified for an element in an XML request or response document.

The following example shows how to specify a null value for the element <HoldTime>:

<Neighbor>
  <Timers>
    <KeepAlive>60</KeepAlive>
    <HoldTime xsi:nil="true"/>
  </Timers>
</Neighbor>

Any element that can be set to "nil" in an XML instance has the attribute "nillable" set to "true" in the XML schema definition for that element. For example:

<xsd:element name="HoldTime" type="xsd:unsignedInt" nillable="true"/>

Any XML instance document that uses the nil mechanism must declare the "XML Schema for Instance Documents" namespace, which contains the "xsi:nil" definition. Responses to native data operations returned from the Cisco CRS-1 Series router declares the namespace in the operation tag. For example:

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

When structuring an XML request, the user should remember the following general rule regarding what to specify in the XML for an operation to take place: As a client XML request is parsed by the
Cisco CRS-1 Series router, the specified operation takes place whenever a closing tag is encountered after a series of one or more opening tags (but only when the closing tag is not the </Naming> tag).

The following example shows a request to get the BGP timer values for a particular BGP autonomous system. In this example, the <Get> operation is triggered when the <GlobalTimers/> tag is encountered.

Sample XML Client Request to Trigger a <Get> Operation for BGP Timer Values

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <Global>
            <GlobalTimers/>
          </Global>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>1</AS>
          </Naming>
          <Global>
            <GlobalTimers>
              <Keepalive>60</Keepalive>
              <Holdtime>180</Holdtime>
            </GlobalTimers>
          </Global>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Response>
Native Data Operation Examples

These sections provide examples of the basic <Set>, <Get>, and <Delete> operations:

• Set Configuration Data Request: Example

• Get Request: Example

• Get Request of Nonexistent Data: Example

• Delete Request: Example

Set Configuration Data Request: Example

The following example shows a native data request to set several configuration values for a particular BGP neighbor. Because the <Set> operation in this example is successful, the response contains only the <Set> operation and <Configuration> request type tags.

This request is equivalent to the following CLI commands:

router bgp 3
  neighbor 10.0.101.6
    remote-as 6
    ebgp-multihop 255
    address-family ipv4 unicast
      prefix-list orf in
      capability orf prefix-list both
    exit
    address-family ipv4 multicast
      prefix-list orf in
    exit
  exit
exit
Sample XML Client Request to <Set> Configuration Values for a BGP Neighbor

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
    <Set>
      <Configuration>
        <BGP MajorVersion="1" MinorVersion="0">
          <AS>
            <Naming>
              <AS>3</AS>
            </Naming>
            <BGPEntity>
              <NeighborTable>
                <Neighbor>
                  <Naming>
                    <IPAddress>
                      <IPV4Address>10.0.101.6</IPV4Address>
                    </IPAddress>
                  </Naming>
                  <RemoteAS>6</RemoteAS>
                  <EBGPMultihopMaxHopCount>255</EBGPMultihopMaxHopCount>
                  <NeighborAFTable>
                    <NeighborAF>
                      <Naming>
                        <AF>IPv4Unicast</AF>
                      </Naming>
                      <Activate>true</Activate>
                      <PrefixListFilterIn>orf</PrefixListFilterIn>
                      <AdvertiseORF>Both</AdvertiseORF>
                    </NeighborAF>
                    <NeighborAF>
                      <Naming>
                        <AF>IPv4Multicast</AF>
                      </Naming>
                      <Activate>true</Activate>
                      <PrefixListFilterIn>orf</PrefixListFilterIn>
                    </NeighborAF>
                  </NeighborAFTable>
                </Neighbor>
              </NeighborTable>
            </BGPEntity>
          </AS>
        </BGP>
      </Configuration>
    </Set>
  </Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Set>
    <Configuration/>
  </Set>
</Response>
Get Request: Example

The following example shows a native data request to get the address independent configuration values for a specified BGP neighbor (using the same values set in the previous example).

Sample XML Client Request to <Get> Configuration Values for a BGP Neighbor

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
       <AS>
         <Naming>
           <AS>3</AS>
         </Naming>
          <BGPEntity>
           <NeighborTable>
             <Neighbor>
               <Naming>
                 <IPAddress>
                    <IPV4Address>10.0.101.6</IPV4Address>
                  </IPAddress>
                </Naming>
              </Neighbor>
            </NeighborTable>
          </BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
          <Naming>
            <AS>3</AS>
          </Naming>
          <BGPEntity>
            <NeighborTable>
              <Neighbor>
                <Naming>
                  <IPAddress>
                    <IPV4Address>10.0.101.6</IPV4Address>
                  </IPAddress>
                </Naming>
                <RemoteAS>6</RemoteAS>
                <EBGPMultihopMaxHopCount>255</EBGPMultihopMaxHopCount>
                <NeighborAFTable>
                  <NeighborAF>
                    <Naming>
                      <AF>IPv4Unicast</AF>
                    </Naming>
                    <Activate>true</Activate>
                    <PrefixListFilterIn>orf</PrefixListFilterIn>
                    <AdvertiseORF>Both</AdvertiseORF>
                  </NeighborAF>
                  <NeighborAF>
                    <Naming>
                      <AF>IPv4Multicast</AF>
                    </Naming>
                    <Activate>true</Activate>
                    <PrefixListFilterIn>orf</PrefixListFilterIn>
                  </NeighborAF>
                </NeighborAFTable>
              </Neighbor>
            </NeighborTable>
          </BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Response>
Get Request of Nonexistent Data: Example

The following example shows a native data request to get the configuration values for a particular BGP neighbor similar to the previous example. However, in this example the client application is requesting the configuration for a nonexistent neighbor. Instead of returning an error, the Cisco CRS-1 Series router returns the requested object class hierarchy, but without any data.

Note Whenever a client application attempts to get nonexistent data, the Cisco CRS-1 Series router usually cannot treat this as an error and returns the empty object class hierarchy in the response.

Sample XML Client Request to <Get> Configuration Data for a Nonexistent BGP Neighbor

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
         <Naming>
           <AS>3</AS>
         </Naming>
          <BGPEntity>
           <NeighborTable>
             <Neighbor>
               <Naming>
                 <IPAddress>
                   <IPV4Address>10.0.101.99</IPV4Address>
                 </IPAddress>
               </Naming>
             </Neighbor>
           </NeighborTable>
         </BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Get>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
         <Naming>
            <AS>3</AS>
         </Naming>
         <BGPEntity>
            <NeighborTable>
             <Neighbor>
                <Naming>
                  <IPAddress
                    <IPV4Address>10.0.101.99</IPV4Address>
                  </IPAddress
                </Naming>
                 .
                 .
                 .
                    no data returned
                 .
                 .
                 .
              <Neighbor>
            </NeighborTable>
          </BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Get>
</Response>
Delete Request: Example

The following example shows a native data request to delete the address-independent configuration for a particular BGP neighbor. Note that if a request is made to delete an item that does not exist in the current configuration, an error is not returned to the client application. So in the following example, the returned result is the same as in the previous example: the empty <Delete/> tag, whether or not the specified BGP neighbor exists.

This request is equivalent to the following CLI commands:

router bgp 3
  no neighbor 10.0.101.9
exit

Sample XML Client Request to <Delete> the Address-Independent Configuration Data for a BGP Neighbor

<?xml version="1.0" encoding="UTF-8"?>
<Request MajorVersion="1" MinorVersion="0">
  <Delete>
    <Configuration>
      <BGP MajorVersion="1" MinorVersion="0">
        <AS>
         <Naming>
           <AS>3</AS>
         </Naming>
         <BGPEntity>
          <NeighborTable>
            <Neighbor>
              <Naming>
                <IPAddress>
                  <IPV4Address>10.0.101.9</IPV4Address>
                </IPAddress>
              </Naming>
            </Neighbor>
           </NeighborTable>
         </BGPEntity>
        </AS>
      </BGP>
    </Configuration>
  </Delete>
</Request>
Sample XML Response from the Cisco CRS-1 Series Router

<?xml version="1.0" encoding="UTF-8"?>
<Response MajorVersion="1" MinorVersion="0">
  <Delete>
    <Configuration/>
  </Delete>
</Response>

Namespace	Description
<Configuration>	Provides access to the router configuration data analogous to command-line interface (CLI) configuration commands. The allowed operations on configuration data are <Get>, <Set>, and <Delete>.
<Operational>	Provides access to the router operational data and is analogous to CLI show commands. The only operation allowed on operational data is <Get>.
<Action>	Provides access to the action data, for example, the clear commands. The only allowed operation on action data is <Set>.
<AdminOperational>	Provides access to the router administration operational data. The only operation allowed on administration operational data is <Get>.
<AdminAction>	Provides access to the router administration action data, for example, the clear commands. The only allowed operation on administration action data is <Set>.