XML Configuration File Execution Command and NETCONF Operations

6.3 CCAP XML File-Based Configuration

6.3.5 XML Configuration File Execution Command and NETCONF Operations

Since the XML Configuration File downloaded to the CCAP is not automatically executed by the CCAP, it is necessary to define a CCAP CLI command to perform specific parsing and execution actions on a given XML Configuration File.

The CCAP MUST support a CLI command to execute an XML configuration file located on a local file system, where the CCAP executes the operations specified for each element in the file.

The CCAP MUST support the "merge", "replace", and "delete" operations defined in section 7.2 of [RFC 6241]. This specification does not intend to make use of the "create" operation.

All configuration changes of an XML file are conceptually executed simultaneously, without regard to the order of the individual object operations in the file. The actual execution of an XML configuration file is expected to be implemented as a sequence of individual element operations in a vendor-specific order. Individual element operations can succeed or fail; the CCAP will log unsuccessful element operations.

The CCAP MUST NOT reject a configuration object because it is dependent upon or related to a configuration object that occurs later in the configuration file and has not yet been processed.

For example, it is valid to execute an XML configuration file that contains an object_A that refers to a new object_B, when the object_A reference appears earlier in the file than the creation of object_B.

A "Full" XML configuration file is one that is intended to replace the entire set of configuration objects on the CCAP.

A Full XML configuration file will contain the operation="replace" attribute in the <ccap:ccap> tag at the root of the configuration tree. When the CCAP saves or exports the current running-config or the startup-config to an XML format, the CCAP MUST insert operation="replace" in a single top-level <ccap:ccap> tag.

A "Partial" XML configuration file is one that is intended to augment the current running-config, replace a subset of the configuration objects on the CCAP, or to act on "control" objects (such as objects that allow a log to be reset or a diagnostic mode to be enabled).

A Partial XML configuration file will contain all of the parent object containers for the objects being configured, all the way up the configuration hierarchy to the "ccap" container. Because of this, caution must be taken when using the "replace" or "delete" operations. While a "merge" operation will only update the attributes that are explicitly provided in the XML configuration file, the "replace" and "delete" operations act upon all objects within the configuration tree. This could cause the entire device configuration to be deleted.

A Partial XML configuration file using a merge or delete operation may exclude mandatory configurable attributes if they are not a key for the configuration object being acted upon. When a partial configuration is using a merge or delete operation, the CCAP MUST ignore validation errors related to missing mandatory configuration attributes unless the missing attribute is the key for the configuration object being acted upon.

The following is an example of how to use the merge operation to update the configuration of a QAM channel on an existing downstream RF port. The file would have the following structure:17

<ccap:ccap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="2013-04-04" xsi:schemaLocation="urn:cablelabs:params:xml:ns:yang:ccap [email protected]" xmlns:ccap="urn:cablelabs:params:xml:ns:yang:ccap" operation="merge"> <chassis> <slot> <slot-number>1</slot-number> <rf-line-card> <ds-rf-port> <port-number>1</port-number> <down-channel> <channel-index>1</channel-index> <admin-state>up</admin-state> <power-adjust>4096</power-adjust> <frequency>200</frequency> <rf-mute>false</rf-mute> <qam-alias>tnt</qam-alias> <errp-advertising>false</ errp-advertising > </down-channel> </ds-rf-port> </rf-line-card> </slot> </chassis> </ccap:ccap>

Note when performing a merge or delete operation on a partial configuration file, only the attributes that define which instance is being configured are required; in the previous example the following attributes had to be specified: • slot-number attribute of the slot object

• port-number attribute of the downstream-port object • channel-index attribute of the down-channel object

As stated earlier, caution should be used with the delete and replace functions. If the replace operation were used in the place of the "merge" operation in the previous example, the entire ccap tree would be removed, replaced with abbreviated structure shown in the example. To avoid this, when using the replace operation, the operation should be placed within the element that is being acted upon. The following two examples demonstrate how the replace and delete operations can be used for targeted partial configuration updates.

Example XML for Replacing a DownChannel object:

Note that all mandatory attributes of objects in the configuration tree are required when using a replace function; in this example a down-channel object is being replaced, but the mandatory attributes of line-card and downstream- port have to be included, even though they were already configured.18

<ccap:ccap xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" SchemaVersion="2013-04-04" xsi:schemaLocation="urn:cablelabs:params:xml:ns:yang:ccap [email protected]" xmlns:ccap="urn:cablelabs:params:xml:ns:yang:ccap" operation="replace"> <chassis> <slot> <slot-number>1</slot-number> <rf-line-card> <rf-card> <line-card-name>DS RF 1</line-card-name> <admin-state>up</admin-state> </rf-card> <ds-rf-port> <port-number>1</port-number> <admin-state>up</admin-state> <down-channel> <channel-index>1</channel-index> <admin-state>down</admin-state> <power-adjust>0</power-adjust> <frequency>0</frequency> <rf-mute>false</rf-mute> <qam-alias>String</qam-alias> <errp-advertising>true</errp-advertising> </down-channel> </ds-rf-port> </rf-line-card> </slot> </chassis> </ccap:ccap>

Example XML for Deleting a DownChannel Object:19

The CCAP will support only one occurrence of the same NETCONF operation ("merge", "replace", or "delete") in a single file. If an operator needs to perform more than one operation type to configure the CCAP, separate

configuration files will need to be created and the operator will execute those files sequentially.

If an XML configuration file does not contain one and only one explicit operation type value of "merge", "replace", or "delete", upon attempted execution of the file, the CCAP MUST reject the entire file, make no changes to the running-config, and log the fatal error as an event with a severity level "Warning" (Event ID: 70000108). If the ccap:ccap node in the XML configuration file has a "replace" operation value, and the subtree in the XML configuration file for that node is missing one or more mandatory elements (either standard elements or vendor-

Revised the following text per CCAP-OSSI-N-13.1095-2 by CP on 3/11/13.

extensions), then the CCAP MUST retain the mandatory elements, attempt the execution of the remaining elements in the file, and log the non-fatal errors as an event with a severity level "Error" (Event ID: 70000107).

The CCAP MUST allow the pre-provisioning of configuration objects associated with line cards that are not yet present in the chassis.

Note that if a "replace" operation value is used, and parts of the subtree in the XML configuration file are missing one or more non-mandatory (vendor-specific or standard) elements, then the CCAP deletes the absent non- mandatory elements from its running-config.

Conversely, for a "merge" operation, the CCAP MUST preserve both standard and vendor-extension objects in the affected subtree that are not present in the merged XML configuration file.

For a "delete" operation, the CCAP MUST delete both standard and vendor-extension objects in the affected subtree.

If an XML configuration file contains an explicit "create" operation value, upon attempted execution of the file the CCAP MUST reject the entire file, make no changes to the running-config, and log the fatal error as an event with a severity level of "Warning" (Event ID: 70000108).

In document Data-Over-Cable Service Interface Specifications Converged Cable Access Platform (CCAP ) Operations Support System Interface Specification (Page 34-37)