The YANG models configure a feature, retrieve the operational state of the router, and perform actions.

Note	The gRPC YANG path or JSON data is based on YANG module name and not YANG namespace.

(snippet)
module Cisco-IOS-XR-aaa-locald-cfg {

  /*** NAMESPACE / PREFIX DEFINITION ***/

  namespace "http://cisco.com/ns/yang/Cisco-IOS-XR-aaa-locald-cfg";


  prefix "aaa-locald-cfg";

  /*** LINKAGE (IMPORTS / INCLUDES) ***/

  import Cisco-IOS-XR-types { prefix "xr"; }

  import Cisco-IOS-XR-aaa-lib-cfg { prefix "a1"; }

  /*** META INFORMATION ***/

  organization "Cisco Systems, Inc.";
										.........................
										......................... (truncated)

Example: Operational YANG Model for AAA

The YANG models used to retrieve operational data is denoted by -oper.

 (snippet)
module Cisco-IOS-XR-aaa-locald-oper {

  /*** NAMESPACE / PREFIX DEFINITION ***/

  namespace "http://cisco.com/ns/yang/Cisco-IOS-XR-aaa-locald-oper";


  prefix "aaa-locald-oper";

  /*** LINKAGE (IMPORTS / INCLUDES) ***/

  import Cisco-IOS-XR-types { prefix "xr"; }

  include Cisco-IOS-XR-aaa-locald-oper-sub1 {
    revision-date 2015-01-07;
  }

  /*** META INFORMATION ***/

  organization "Cisco Systems, Inc.";
				........................
				........................ (truncated)

Note	A module can include any number of sub-modules; each sub-module belongs to only one module. The names of all standard modules and sub-modules must be unique.

 (snippet)
clear ospfv3 1 vrf vrf1 statistics neighbor 2.2.2.2
RPC message based on the new ospfv3 yang model- 
 <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <act-ospfv3-instance-vrf xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-ipv6-ospfv3-act">
      <instance>
        <instance-identifier>1</instance-identifier>
         <vrf>
          <vrf-name>vrf1</vrf-name>
          <stats>
           <neighbor>
            <neighbor-id>2.2.2.2</neighbor-id>
           </neighbor>
          </stats>
         </vrf>
      </instance>
    </act-ospfv3-instance-vrf>
 </rpc>

YANG data models can be represented in a hierarchical, tree-based structure with nodes. This representation makes the models easy to understand.

Each feature has a defined YANG model, which is synthesized from schemas. A model in a tree format includes:

• Top level nodes and their subtrees

• Subtrees that augment nodes in other YANG models

• Custom RPCs

module: Cisco-IOS-XR-cdp-cfg
   +--rw cdp
      +--rw timer?               uint32
      +--rw advertise-v1-only?   empty
      +--rw enable?              boolean
      +--rw hold-time?           uint32
      +--rw log-adjacency?       empty
augment /a1:interface-configurations/a1:interface-configuration:
   +--rw cdp
      +--rw enable?   empty

augment "/a1:interface-configurations/a1:interface-configuration" {
    container cdp {
      description "Interface specific CDP configuration";
      leaf enable {
        type empty;
        description "Enable or disable CDP on an interface";
      }
    }
    description
      "This augment extends the configuration data of
      'Cisco-IOS-XR-ifmgr-cfg'";
  }
 

module: Cisco-IOS-XR-cdp-oper
   +--ro cdp
      +--ro nodes
         +--ro node* [node-name]
            +--ro neighbors
            |  +--ro details
            |  |  +--ro detail*
            |  |     +--ro interface-name?   xr:Interface-name
            |  |     +--ro device-id?        string
            |  |     +--ro cdp-neighbor*
            |  |        +--ro detail
            |  |        |  +--ro network-addresses
            |  |        |  |  +--ro cdp-addr-entry*
            |  |        |  |     +--ro address
            |  |        |  |        +--ro address-type?   Cdp-l3-addr-protocol
            |  |        |  |        +--ro ipv4-address?   inet:ipv4-address
            |  |        |  |        +--ro ipv6-address?   In6-addr
            |  |        |  +--ro protocol-hello-list
            |  |        |  |  +--ro cdp-prot-hello-entry*
            |  |        |  |     +--ro hello-message?   yang:hex-string
            |  |        |  +--ro version?               string
            |  |        |  +--ro vtp-domain?            string
            |  |        |  +--ro native-vlan?           uint32
            |  |        |  +--ro duplex?                Cdp-duplex
            |  |        |  +--ro system-name?           string
            |  |        +--ro receiving-interface-name?   xr:Interface-name
            |  |        +--ro device-id?                  string
            |  |        +--ro port-id?                    string
            |  |        +--ro header-version?             uint8
            |  |        +--ro hold-time?                  uint16
            |  |        +--ro capabilities?               string
            |  |        +--ro platform?                   string

............................................... (truncated)

This feature addresses some of the issues identified with native ACL YANG models that affect usability of the YANG model. It improves user-friendliness and standards compliance in the following native ACL YANG models:

• Cisco-IOS-XR-es-acl-cfg

• Cisco-IOS-XR-ipv4-acl-cfg

• Cisco-IOS-XR-ipv6-acl-cfg

The following issues are addressed as part of this enhancement:

• Lack of revision dates and descriptions

  Problem: When the revision changed on an ACL-model YANG file, the changes associated with the new revision were not accurately described.

  Solution: Includes description for the changes made in each subsequent version without removing the information for the previous versions.

  Example from Cisco-IOS-XR-ipv4-acl-cfg.yang :

  
   revision "2018-04-03" {
      description
        "6.5.1 revision. Correct enum value for Next-hop-type.";
    }       
            
    revision "2018-03-23" {
      description
        "6.5.1 revision. Removing none-next-type.";
    } 
  

• Unconstrained use of strings

  Problem: ACL native models use leaves defined as string type; however, the string length is undefined or incorrect.

  Solution: Pattern and length checking is added to leaves using string types. This allows NETCONF to control these checks, rather than relying on ACL verifier at commit time.

  In the following example, the length of the string is limited to 255 characters and only alphanumeric characters are allowed.

  typedef my-base-str-type { type string {
  length "1..255";
  pattern "[0-9a-fA-F]*";
  } }

• Lack of good description statements

  Problem: Most leaves in the native ACL models had description fields that did not have good description, which impacts the ease of use and understanding of the YANG model.

  Solution: Leaf description fields are updated to provide useful information.

• Lack of verification and inconsistent behavior across ACL-range leaves

  Problem: YANG model supports different combinations of leaves for containers with upper value, lower value and operator leaves. As a result, some of the configurations can be invalid from the CLI perspective.

  Solution: The native ACL models are improved to include various combinations of leaves that are supported by the YANG model. Also, the parsing behavior across all ACL-range leaves are aligned to remain consistent.

• Inconsistency between protocol-operator input and output

  Problem: NETCONF output should be consistent with user input.

  Solution: The protocol-operator leaf is made as non-mandatory, and need not be set to equal.

NETCONF provides mechanisms to install, manipulate, or delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data, as well as protocol messages. Use ssh server capability netconf-xml command to enable NETCONF to reach XML subsystem via port 22. NETCONF uses a simple RPC-based (Remote Procedure Call) mechanism to facilitate communication between a client and a server. The client can be a script or application that runs as part of a network manager. The server is a network device such as a router.

NETCONF Layers

NETCONF can be partitioned into four layers:

• Content layer: includes configuration and notification data

• Operations layer: defines a set of base protocol operations invoked as RPC methods with XML-encoded parameters

• Messages layer: provides a simple, transport-independent framing mechanism for encoding RPCs and notifications

• Secure Transport layer: provides a communication path between the client and the server

For more information about NETCONF, refer RFC 6241.

gRPC is an open-source RPC framework. It is based on Protocol Buffers (Protobuf), which is an open source binary serialization protocol. gRPC provides a flexible, efficient, automated mechanism for serializing structured data, like XML, but is smaller and simpler to use. The user needs to define the structure by defining protocol buffer message types in .proto files. Each protocol buffer message is a small logical record of information, containing a series of name-value pairs.

gRPC encodes requests and responses in binary. gRPC is extensible to other content types along with Protobuf. The Protobuf binary data object in gRPC is transported over HTTP/2.

Note

It is recommended to configure TLS before enabling gRPC. Enabling gRPC protocol uses the default HTTP/2 transport with no TLS enabled on TCP. gRPC mandates AAA authentication and authorization for all gRPC requests. If TLS is not configured, the authentication credentials are transferred over the network unencrypted. Non-TLS mode can only be used in secure internal network.

gRPC supports distributed applications and services between a client and server. gRPC provides the infrastructure to build a device management service to exchange configuration and operational data between a client and a server. The structure of the data is defined by YANG models.

Cisco gRPC IDL uses the protocol buffers interface definition language (IDL) to define service methods, and define parameters and return types as protocol buffer message types. The gRPC requests are encoded and sent to the router using JSON. Clients can invoke the RPC calls defined in the IDL to program the router.

syntax = "proto3";
 
package IOSXRExtensibleManagabilityService;
 
service gRPCConfigOper {
 
    rpc GetConfig(ConfigGetArgs) returns(stream ConfigGetReply) {};
  
    rpc MergeConfig(ConfigArgs) returns(ConfigReply) {};
 
    rpc DeleteConfig(ConfigArgs) returns(ConfigReply) {};
 
    rpc ReplaceConfig(ConfigArgs) returns(ConfigReply) {};
 
    rpc CliConfig(CliConfigArgs) returns(CliConfigReply) {};
 
    rpc GetOper(GetOperArgs) returns(stream GetOperReply) {};
 
    rpc CommitReplace(CommitReplaceArgs) returns(CommitReplaceReply) {};
} 
message ConfigGetArgs {
     int64 ReqId = 1;
     string yangpathjson = 2;
}
 
message ConfigGetReply {
    int64 ResReqId = 1;
    string yangjson = 2;
    string errors = 3;
}
 
message GetOperArgs {
     int64 ReqId = 1;
     string yangpathjson = 2;
}
 
message GetOperReply {
    int64 ResReqId = 1;
    string yangjson = 2;
    string errors = 3;
}
 
message ConfigArgs {
    int64 ReqId = 1;
    string yangjson = 2;
 
}
 
message ConfigReply {
    int64 ResReqId = 1;
    string errors = 2;
}
 
message CliConfigArgs {
    int64 ReqId = 1;
    string cli = 2;
}
 
message CliConfigReply {
    int64 ResReqId = 1;
    string errors = 2;
}

message CommitReplaceArgs {
     int64 ReqId = 1;
     string cli = 2;
     string yangjson = 3;
}

message CommitReplaceReply {
     int64 ResReqId = 1;
     string errors = 2;
}

service gRPCExec {
    rpc ShowCmdTextOutput(ShowCmdArgs) returns(stream ShowCmdTextReply) {};
    rpc ShowCmdJSONOutput(ShowCmdArgs) returns(stream ShowCmdJSONReply) {};
    rpc ActionJSON(ActionJSONArgs) returns(stream ActionJSONReply) {};
}

message ShowCmdArgs {
     int64 ReqId = 1;
     string cli = 2;
}
 
message ShowCmdTextReply {
    int64 ResReqId =1;
    string output = 2;
    string errors = 3;
}

message ActionJSONArgs {
	int64 ReqId = 1;
	string yangpathjson = 2;
}

message ActionJSONReply {
	int64 ResReqId = 1;
	string yangjson = 2;
	string errors = 3;
}

service OpenConfiggRPC {
     rpc SubscribeTelemetry(SubscribeRequest) returns (stream SubscribeResponse) {};
     rpc UnSubscribeTelemetry(CancelSubscribeReq) returns (SubscribeResponse) {};
     rpc GetModels(GetModelsInput) returns (GetModelsOutput) {};
}

message GetModelsInput {
     uint64  requestId   = 1;
     string  name        = 2;
    string  namespace   = 3;
    string  version     = 4;
    enum MODLE_REQUEST_TYPE {
         SUMMARY = 0;
         DETAIL  = 1;
     }
     MODLE_REQUEST_TYPE requestType = 5;
}

message GetModelsOutput {
     uint64  requestId   = 1;
     message ModelInfo {
         string  name        = 1;
         string  namespace   = 2;
        string  version     = 3;
         GET_MODEL_TYPE  modelType = 4;
         string modelData = 5;
     }
     repeated ModelInfo models = 2;
     OC_RPC_RESPONSE_TYPE responseCode = 3;
     string msg = 4;
}