NETCONF and ConfD

This chapter describes NETCONF and the StarOS process called ConfD manager.

It contains the following sections:

Overview

StarOS provides a northbound NETCONF interface that supports a YANG data model for transferring configuration and operational data with the Cisco Network Service Orchestrator (NSO). It also incorporates a ConfD engine to communicate with the NSO management console.

NETCONF (Network Configuration Protocol) is a network management protocol developed and standardized by the IETF (RFC 6241). It provides mechanisms to install, manipulate, and delete the configuration of network devices. Its operations are realized on top of a simple remote procedure call (RPC) layer. The NETCONF protocol uses XML-based data encoding for the configuration data as well as the protocol messages. The protocol messages are exchanged on top of a secure transport protocol.

ConfD is an on-device management framework that provides a set of interfaces to manage a device. The ConfD framework automatically renders all the management interfaces from a data-model. ConfD implements the full NETCONF specification and runs over SSH with content encoded in XML.

ConfD is configured to allow only authenticated/authorized access through external authentication. ConfD Manager provides a standalone CLI module for ConfD to invoke when authenticating/authorizing any new users. ConfD is configured to allow only authorized access through StarOS authentication. Upon authentication, the user is given a privilege level (0-15) which is mapped to StarOS secure admin, admin, operator, and inspector, as defined in the YANG model. StarOS logs CLI authentication event/status messages for each ConfD authentication request.

On the southbound side, ConfD communicates with a StarOS process called via a set of APIs provided by the ConfD management agent. The ConfD Configuration Database (CDB) is used by ConfD to store objects. StarOS accesses the database through the ConfD-supplied APIs. Once the ConfD configuration database is populated, StarOS continues to allow CLI access to modify the overall configuration. There are no automatic updates to the CDB as a result. The CDB only receives updates via the NETCONF interface. In order to keep the CDB and the StarOS configuration databases in sync, all changes made via CLI access (external to NETCONF) to YANG model supported configuration objects must be applied to the CDB manually.

YANG is a data modeling language for the NETCONF network configuration protocol. It can be used to model both configuration data as well as state data of network elements. YANG can also be used to define the format of event notifications emitted by network elements and it allows data modelers to define the signature of remote procedure calls that can be invoked on network elements via the NETCONF protocol (RFC 6020). The YANG file is compiled as part of StarOS and incorporates a subset of the existing StarOS supported CLI commands.

In this release, the YANG model supports a limited set of ECS configuration commands via NSO. For additional information, refer to NSO user documentation and Supported StarOS ECS Configuration Commands.

Figure 1. NETCONF System Flow

Configuring ConfD

To enable NETCONF protocol in StarOS, you must enable server confd and enter the NETCONF Protocol Configuration mode. The NETCONF Protocol Configuration mode supports optional configuration commands.

SSH Key Requirement

NETCONF-ConfD support requires that a V2-RSA SSH key be configured on the local context.

If an SSH key is not available, StarOS generates an error message. 

Failure: The ConfD (NETCONF) server requires an RSA key on the local context

You can run the show ssh key command to verify the existence of an SSH key on the system.

If an SSH key is not available, see the Configuring SSH Options section of the Getting Started chapter in this guide.

NETCONF Protocol Configuration Mode

The NETCONF protocol is enabled via the Context Configuration mode server conf command. This command is restricted to the local context only. 

[local]host_name# configure 
[local]host_name(config)# context local 
[local]host_name(config-ctx)# server confd 
[local]host_name(config-confd)# ? 
  autosave-config      - Automatically saves current configuration to the URL specified  
                         whenever a change is applied through ConfD interfaces 
  confd-user           - Configures the default login user with full administrator rights  
                         for the ConfD server. 
  end                  - Exits configuration mode and returns to Exec Mode 
  exit                 - Exits current configuration mode, returning to previous mode 
  no                   - Enables/Disables the followed option

The autosave-config and confd-user keywords are optional.

To disable NETCONF protocol, run the Global Configuration mode no server confd command.

For additional information, see the NETCONF Protocol Configuration Mode Commands chapter of the Command Line Interface Reference.

autosave-config

This NETCONF Protocol Configuration mode command automatically saves the current ConfD configuration to a specified URL whenever a change is applied by NSO through the ConfD interface in the CLI based model. By default this command is disabled.

The command syntax is: autosave-config <url>, where [ file: ]{/flash | /usb1 | /hd-raid | /sftp} [ /<directory>] /<filename>.

confd-user

This NETCONF Protocol Configuration mode command associates a username for all CLI operations via NETCONF. The user will be authenticated with verifiable credentials. This username is used for CLI logging purposes only.

The command syntax is: confd-user <username> , where <username> is an alphanumeric string of 1 to 144 characters.


Important

The NETCONF or RESTful session must still be established with verifiable credentials.

Seeding and Synchronizing the CDB

After enabling server confd you may need to initially seed the CDB with a local copy of the configuration database (CDB) managed by ConfD on StarOS. The seeding procedure creates a CDB used by ConfD on the StarOS platform that contains all CLI based YANG model supported configuration commands.


Important
  • If you manually modify a managed object via the StarOS CLI, you must resynchronize the running configuration with the NSO by repeating the procedure described below.

Procedure

Step 1

Run Exec mode save configuration <url> confd to save the ConfD supported StarOS configuration data to a file on the /flash device.

Step 2

Run Exec mode show configuration error to validate the saved configuration. Correct any errors before applying the configuration. Otherwise, ConfD will reject the entire configuration.

Step 3

Run Exec mode configure confd <url> to apply the ConfD configuration. Once the ConfD configuration is applied, the device is ready to establish NETCONF connections to the NSO management service.

Step 4

Synchronize the device with your NSO. Refer to NSO user documentation for detailed information on the synchronization process.

Sample Configuration

The following command sequence establishes a COnfD configuration in support of NETCONF protocol.

A type v2-RSA SSH key is required for enabling server confd. 

configure 
  context local 
      ssh key 
<encrypted key text> 
len 938 type v2-rsa 
    server confd 
      confd-user NETCONF 
      autosave-config /flash/config.cfg 
    #exit 
    subscriber default 
    exit 
    aaa group default 
    #exit 
    gtpp group default 
    #exit 
  #exit 
end
Notes:

  • confd-user and autosave-config are optional. Just configuring server confd enables NETCONF support.

Verifying the Configuration

There are two Exec mode show commands that display information about the NETCONF-ConfD configuration.

show confdmgr Command

This command displays information about the StarOS ConfD Manager (confdmgr) process.

The syntax for this command is: 

show confdmgr { confd { cdb | netconf | state } | subscriptions }

Notes:

See below for a sample output for show confdmgr:

  • The confd keyword displays the following options:

    • cdb displays ConfD CDB information

    • netconf displays NETCONF state information

    • state displays current ConfD state information

  • The subscriptions keyword displays ConfD CDB subscription information. 

[local]<host_name># show confdmgr 
 
State Information 
----------------- 
State               Started 
Subscriptions       2 
Last successful id  1461-704882-705350 
Last failed id      None 
Autosave url        Not configured 
Username            Not configured 
 
Statistics 
---------- 
Triggers                  1 
Notifications             2 
Successful notifications  2 
Failed notifications      0 
Unexpected                0 
[local]<host_name>#

The Statistics portion of this output includes the following information:

  • Triggers – Number of times confdmgr has requested ConfD to dump the CDB contents back into confdmgr which results in a config synchronization by SCT (Shared configuration Task).

  • Notifications – Number of times ConfD has sent an update to confdmgr.

  • Successful Notifications – Number of times an update received from ConfD was successfully processed.

  • Failed Notifications – Number of times an update received from ConfD was not processed successfully. The number of successes and failures should always equal the total number of notifications.

  • Unexpected – Number of times an unexpected condition was encountered. An error log is generated for each case.

See below for a sample output for show confdmgr confd cbd: 

[local]<host_name># show confdmgr confd cdb 
active-charging service acs 
exit 
context local 
 server confd 
  autosave-config /tmp/ut_confdmgr_config.txt 
  confd-user      confd_user 
 exit 
exit 
nacm read-default permit 
nacm groups group admin 
! 
nacm groups group inspector 
! 
nacm groups group operator 
! 
nacm groups group secure_admin 
! 
nacm rule-list secure_admin 
! 
 group [ secure_admin ] 
 rule any-access 
  action permit 
! 
 rule secure_admin_server_confd 
  module-name       cisco-staros-cli-config 
  path              /context/server/confd 
  access-operations create,read,update 
  action            permit 
  | 
  | 
  V 
nacm rule-list inspector 
 group [ inspector ] 
 rule any-access 
  access-operations read 
  action            permit 
 ! 
! 
[local]<host_name>#

See below for a sample output for show confdmgr confd netconf: 

[local]<host_name># show confdmgr confd netconf 
netconf-state capabilities capability urn:ietf:params:netconf:base:1.0 
netconf-state capabilities capability urn:ietf:params:netconf:base:1.1 
netconf-state capabilities capability urn:ietf:params:netconf:capability:writable-running:1.0 
netconf-state capabilities capability urn:ietf:params:netconf:capability:candidate:1.0 
 | 
 | 
 V 
netconf-state statistics netconf-start-time 2016-03-30T17:09:49-04:00 
netconf-state statistics in-bad-hellos 0 
netconf-state statistics in-sessions 0 
netconf-state statistics dropped-sessions 0 
netconf-state statistics in-rpcs 0 
 | 
 | 
 V 
netconf-state datastores datastore candidate 
NAME         CREATOR  CREATED                    CONTEXT 
---------------------------------------------------------- 
/rollback0   admin    2016-04-26T17:08:02-00:00  noaaa 
/rollback1   admin    2016-04-26T17:07:57-00:00  noaaa 
/rollback2   admin    2016-04-26T17:07:49-00:00  noaaa 
/rollback3   admin    2016-04-26T17:07:49-00:00  noaaa 
/rollback4   admin    2016-04-26T17:07:47-00:00  noaaa 
 | 
 | 
 V 
/cli-history/admin.hist 
/cli-history/root.hist 
/global.data 
 
[local]<host_name>#

See below for a sample output for show confdmgr confd state: 

[local]<host_name># show confdmgr confd state
Monday June 24 10:58:49 EDT 2019
confd-state version 7.1
confd-state epoll false
confd-state daemon-status started
confd-state loaded-data-models data-model acs-config
 revision        2016-10-31
 namespace       http://www.cisco.com/usp/nfv/acs-config
 prefix          acs-config
 exported-to-all
confd-state loaded-data-models data-model cisco-staros-bulkstats
 revision        2016-12-14
 namespace       http://www.cisco.com/staros-bulkstats
 prefix          staros_bulkstats
 exported-to-all
confd-state loaded-data-models data-model cisco-staros-cli-config
 revision        2016-12-14
 namespace       http://www.cisco.com/staros-cli-config
 prefix          staros_cli
 exported-to-all
confd-state loaded-data-models data-model cisco-staros-config
 revision        2016-12-14
 namespace       http://www.cisco.com/staros-config
 prefix          staros_config
 exported-to-all
confd-state loaded-data-models data-model cisco-staros-exec
 revision        2016-12-14
 namespace       http://www.cisco.com/staros-exec
 prefix          staros_exec
 exported-to-all
confd-state loaded-data-models data-model cisco-staros-kpi
 revision        2017-10-31
 namespace       http://www.cisco.com/staros-kpi

See below for a sample output for show confdmgr subscriptions: 

[local]<host_name># show confdmgr subscriptions 
 
Subscriptions: 
Path                               Index  Namespace 
--------------------------------------------------- 
/active-charging                       6     staros 
/context                               7     staros 
[local<host_name>#

Subscriptions are configuration points defined in the Yang model for which confdmgr wants to be notified when a change occurs. In this release there are two subscriptions: “/active-charging” and “/context”.

show configuration confd Command

The confd keyword filters the output of the show configuration command to display only configuration commands that are supported by the YANG model. 

show configuration confd

A sample output appears below. 

[local]<host_name># show configuration confd 
config 
  context local 
    server confd 
    #exit 
  active-charging service ecs 
    ruledef rd1 
      tcp any-match = TRUE 
    #exit 
    rulebase default 
    #exit 
  #exit 
end 
[local]<host_name>#

clear confdmgr statistics

This command clears everything listed in the "Statistics" section of the output of the show confdmgr command, including:

  • Triggers

  • Notifications

  • Successful notifications

  • Failed notifications

  • Unexpected

Show Support Details (SSD)

The output of all show confdmgr commands has been added to the SSD.

CDB Maintenance

A local copy of the ConfD Configuration Database (CDB) is managed by ConfD on StarOS.

You can show and save all ConfD supported StarOS configuration commands to a URL. The confd keyword has been added to the show configuration and save configuration commands for these purposes.

After saving a ConfD-supported configuration to a URL, you can apply it directly to the CDB via the Exec mode configure confd <url> command. This command applies the contents of the file at the url to the running configuration of ConfD.

Additional detail regarding the above commands is provided below.

clear confdmgr confd cdb

This Exec mode command erases the configuration in the ConfD Configuration Database (CDB) which is used by ConfD to store configuration objects. StarOS accesses the database via ConfD-supplied APIs.


Note

The CDB cannot be erased unless the Context Configuration mode no server confd command is run in the local context to disable ConfD and NETCONF protocol support.

The following is a sample command sequence for clearing the CDB: 

[local]host_name# config 
[local]host_name(config)# context local 
[local]host_name(config-ctx)# no server confd 
[localhost_name(config-ctx)# end 
[local]host_name# clear confdmgr confd cdb 
About to delete the ConfD configuration database 
The running configuration is NOT affected. 
Are you sure? [Yes|No]: y 
[local]host_name#

Caution

Clearing the CDB is a terminal operation. The CDB must be repopulated afterwards.


Important

When both confd and bulkstats configurations are present, the CDB stores the schemas from the bulkstats configuration. During startup, the bulkstats configuration in confd database takes precedence over the startup file configuration. To ensure the startup configuration takes effect, it is strongly recommended to clear the CDB before reloading the chassis.

configure confd <url>

This Exec mode command applies the contents of the configuration script specified by the URL to the current ConfD configuration database (CDB).

A sample command sequence is provided below. 

[local]host_name# save configuration /flash/confd.config confd 
[local]host_name# configure confd /flash/confd.config 
Info: #!$$ StarOS V20.2 Chassis 52767e9ff9e207bed12c76f7f8a5352c 
Info: config 
Info:   active-charging service acs 
Info:     rulebase default 
Info:     #exit 
Info:   #exit 
Info: end 
[local]host_name#

Note

Executing configure confd does not move you to the Global Configuration mode. The confd keyword is not supported on the ASR 5000.

save configuration <url> confd

The keyword confd is added to the Exec mode save configuration command. This keyword filters the saved configuration commands to contain only configuration commands that are supported by the YANG model.

The command syntax for this process is: 

[local]host_name# save configuration <url> confd

The output of the YANG model subset of configuration commands can be viewed via the show file url <url> command, where <url> is the pathname used to save the configuration. The saved configuration file can then be applied to the CDB using the configure confd command.

Supported StarOS ECS Configuration Commands

For this release, the following StarOS ECS commands are supported for the CLI based YANG model:

  • ruledef <ruledef_name>

    • ip server-ip-address = *

    • tcp-ether-port = *

    • udp ether-port = *

    • tcp either-port-range = *

    • udp ether-port range = *

    • tcp-any-match = *

    • udp any-match = *

    • http url = *

    • httpcookie = *

    • http x-header = *

  • group-of-ruledefs <ruledefs_group_name>

    • add-ruledef priority = *

  • qos-group-of-ruledefs <group_name>

    • add-group-of-ruledef <group_of_ruledef_name>

  • charging-action <charging_action_name>

    • flow-idle-timeout <seconds>

    • content-id 1

    • service-identifier <service_id>

    • billing-action egcdr

  • rulebase <rulebase_name>

    • action priority <priority_number> group-of-ruledefs <ruledefs_group_name> charging-action <charging_action_name>


Note

"= *" indicates support for every option following the prior keyword/value.

ConfD Upgrade Support