Yangcli Operations
Establish Connection
These are the steps to establish a connection between the NetConf client and the server running on the device.
# yangcli server=<ip_address> user=<user_name> password=<password>
ip_address: Address of the device to be managed
user_name & password: User account detail for authentication
The interactive version of this command is shown below:
# yangcli yangcli> connect
Enter string value for leaf <user>
yangcli:connect> <user_name>
Enter string value for leaf <server>
yangcli:connect> <ip_address>
Enter string value for leaf <password>
yangcli:connect> <password>
The OcNOS NetConf server supports both IPv4 and IPv6 connections.
Note: In NETCONF (Network Configuration Protocol), the maximum number of sessions over SSH is indeed a configurable parameter that can be defined in the netconfd.yang module.
Here’s a generalized example of how such a parameter might be defined in a netconfd.yang file
leaf max-sessions {
description
"Specifies the maximum number of sessions
that can be accepted.";
type uint32;
default 1024;
}
At present, the netconfd software is utilizing the default setting of 1024 for the max-sessions parameter. Consequently, the maximum number of concurrent NETCONF sessions is restricted to 1023 due to this default configuration.
Attempting to create the 1024th session in the netconfd deletes the oldest session with session-id 1 and creates a new session with session-id 1.
Configure the Device
Configuration details are placed in an XML file and sent to the netconfd server. You must refer to the OcNOS NetConf Command Reference to prepare the XML based configuration file with the correct hierarchy. If the hierarchy is not correct, yangcli throws an error.
One portion of the BGP protocol module Yang model is presented below. This module is a submodule for the parent OcNOS yang module.
submodule ipi-bgp-peer {
yang-version 1.1;
belongs-to ipi-bgp { prefix ipi-bgp; }
import feature-list {
prefix feature-list;
revision-date 2021-05-03;
}
import cml-data-types {
prefix cml-data-types;
revision-date 2021-05-03;
}
import ipi-bgp-types {
prefix ipi-bgp-types;
revision-date 2021-05-27;
}
revision "2021-06-11" {
description "Added dependency constraint between name and direction attrs for the distribute-list, prefix-list, filter-list and route-map CLI's";
reference " 0.5.4.";
}
grouping peer-grouping {
description
"List of BGP neighbors configured on the local system, uniquely
identified by peer IPv[46] address";
list peer {
when " /bgp/bgp-instance/peer/config/peer-as or /bgp/bgp-instance/peer/config/mapped-peer-group-tag ";
key "peer-address";
description
"List of BGP neighbors configured on the local system, uniquely identified by peer IPv[46] address";
leaf peer-address {
type leafref {
path "../config/peer-address";
}
description "Reference to the address of the BGP peer used as a key in the peer list";
} // END of peer-address definition.
list bgp-password {
when " /bgp/bgp-instance/peer/config/peer-as or /bgp/bgp-instance/peer/config/mapped-peer-group-tag ";
key "password auth-key-encrypt";
max-elements 1;
description
"list for BGP password";
leaf password {
type leafref {
path "../config/password";
}
description "Use this attribute to enable authentication-key";
} // END of password definition.
Based on the hierarchy in the Yang module, the following XML file named bgp.xml is created with the configuration data. The bgp.xml file is referenced in the edit-config operation specified below.
<bgp xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-bgp">
<bgp-instance>
<bgp-as>100</bgp-as>
<config>
<bgp-as>100</bgp-as>
</config>
<timers>
<config>
<hold-time>9</hold-time>
<keep-alive>3</keep-alive>
</config>
</timers>
</bgp-instance>
</bgp>
Use this command to globally set or reset the keepalive and holdtime values for all the neighbors.
yangcli ocnos@10.12.45.253> edit-config config=@/root/bgp.xml
Filling container /edit-config/input/target:\
RPC OK Reply 15 for session 1:
OcNOS supports hitless NetConf merge operation. The hitless feature blocks southbound calls to configure the provisioned configuration if it was already configured. Because of this feature, errors like “QOS already enabled” are not reported when you try to enable QoS again/repeatedly. Also, southbound calls are blocked when you try to delete/unset a non-existing configuration.
Configuration objects are merged while provisioning configuration incrementally (different/same attributes) for the same object. However this cannot be done for attributes or objects having RANGE (such as VLAN range) and MULTIPLE values (such as OSPF passive interface address) type attributes, therefore they are treated as different objects and southbound calls are allowed for every individual object. As per hitless functionality, all these objects are supposed to be merged, and a single object is expected to be sent southbound to do the configuration/un-configuration. But there will be duplicate calls southbound as was present in earlier releases. This limitation is planned to be addressed in upcoming releases.
Note: List of payloads required to configure the switch is documented in NetConf Command Reference guide.
To disable QoS, use edit-config's MERGE operation (default-operation=merge) with the below payload:
<qos xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-qos">
<global>
<config>
<enable-qos operation="delete"/>
</config>
</global>
</qos>
Limitations
edit-config Operation
When using the edit-config operation with the create action and providing only key attributes to create a YANG list that references another YANG list, it will not result in the creation of any new configuration. This is because the referenced list already exists, and only key attributes are specified.
For instance, consider the following payload:
<isis xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-isis">
<interfaces>
<interface operation="create">
<name>eth1</name>
<config>
<name>eth1</name>
</config>
</interface>
</interfaces>
</isis>
In this example, the leaf node /isis/interfaces/interface/config/name serves as a leafref reference to interfaces/interface/name. Essentially, it means that the interface list within the isis module is referring to the interface list in the interface module. The provided payload contains only the key attribute for the interface list, indicating an intention to create a new interface list. However, since the referenced interface already exists, this configuration has no impact.
To make a valid and meaningful configuration change, setting other non-key attributes of the referenced interface list is necessary. For instance, the following payload is both valid and purposeful:
<isis xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-isis">
<interfaces>
<interface operation="create">
<name>eth1</name>
<config>
<name>eth1</name>
<minimal>level-1-only</minimal>
</config>
</interface>
</interfaces>
</isis>
This payload not only specifies the key attribute but also includes additional non-key attributes for the referenced interface list, allowing for a meaningful configuration update.
Default-Operations
1. merge and replace is supported as default-operation.
2. delete, and replace is supported as operations at container and leaf level. (operation="delete"), (operation="replace")
3. create is supported as operation at container level. Create operation is not supported at leaf level. (operation="create").
4. remove is supported as operation at container and leaf level (operation="remove").
Table 3-1: Edit-config operations
| | Default operation |
|---|
| | Merge | Replace | None |
Create | Object | Y | Y | |
Leaf | | | |
Delete | Object | Y | Y | |
Leaf | Y | Y | |
Merge | Object | Y | Y | |
Leaf | Y | Y | |
Replace | Object | Y | Y | |
Leaf | Y | Y | |
Remove | Object | Y | Y | |
Leaf | Y | Y | |
Legend: | Y | Supported |
| Blank | Not supported; error will be returned |
Retrieve Candidate Configuration
Candidate configuration datastore is used to hold configuration data that can be manipulated without impacting the device's current configuration. The candidate configuration is a full configuration data set that serves as a work place for creating and manipulating configuration data. Additions, deletions, and changes can be made to this data to construct the desired configuration data.
Note: All NetConf clients share the single candidate configuration store.
>sget-config /bgp source=candidate
Filling list /bgp:
RPC Data Reply 1 for session 2:
rpc-reply {
data {
bgp {
bgp-instance 100 {
bgp-as 100
config {
bgp-as 100
}
timers {
config {
hold-time 9
keep-alive 3
}
}
}
}
}
Commit Candidate Configuration
A <commit> operation can be performed at any time that causes the device's running configuration to be set to the value of the candidate configuration.
yangcli ocnos@10.12.45.253> commit
RPC OK Reply 16 for session 1
Retrieve Running Configuration
Configuration data is the set of writable data that is required to transform a system from its initial default state into its current state. You can use the get-config operation to fetch the running configuration data.
>sget-config /bgp source=running
Filling list /bgp:
RPC Data Reply 1 for session 2:
rpc-reply {
data {
bgp {
bgp-instance 100 {
bgp-as 100
config {
bgp-as 100
}
timers {
config {
hold-time 9
keep-alive 3
}
}
}
}
}
}
Retrieve Running Configuration and State Data
State data is the additional data on a system that is not configuration data such as read-only status information and collected statistics. You can use the get operation to fetch a protocol module's running configuration and state data.
>sget /bgp rpc-reply {
data {
bgp {
bgp-instance 100 {
bgp-as 100
config {
bgp-as 100
}
state {
bgp-as 100
scan-remain-time 8
router-run-time-ip-address 0.0.0.0
total-prefixes 0
table-version 1
version 4
}
timers {
config {
hold-time 9
keep-alive 3
}
state {
hold-time 9
keep-alive 3
}
}
}
}
}
}
Copy Running Configuration to Startup
> copy-config source=running target=startup
The equivalent OcNOS command is:
# write
Error Messages
NetConf operations return protocol, management layer, and protocol module errors. The example below depicts an error returned by a protocol module.
Copy the content below into bgp_err.xml.
<bgp xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-bgp">
<bgp-instance>
<bgp-as>200</bgp-as>
<config>
<bgp-as>200</bgp-as>
</config>
<timers>
<config>
<hold-time>9</hold-time>
<keep-alive>3</keep-alive>
</config>
</timers>
</bgp-instance>
</bgp>
Execute the following command and commit the changes:
yangcli tbyran@10.12.45.253> edit-config config=@/root/bgp_err.xml
Filling container /edit-config/input/target: RPC OK Reply 12 for session 1:
yangcli tbyran@10.12.45.253> commit
mgr_rpc: got invalid reply on session 1 (invalid XPath expression syntax) RPC Error
Reply 13 for session 1:
rpc-reply {
rpc-error {
error-type application
error-tag operation-failed
error-severity error
error-app-tag general-error
error-path /bgp/bgp-instance[bgp-as='200']/config
error-message '%% BGP is already running, AS is 100'
error-info {
error-number 127
}
}
rpc-error {
error-type application
error-tag operation-failed
error-severity error
error-app-tag general-error
error-path /bgp/bgp-instance[bgp-as='200']/timers/config
error-message '%% AS number mismatch'
error-info {
error-number 4294962321
}
}
}
Warning Messages
NetConf operations return protocol module warnings. The example below depicts a warning returned by a protocol module.
Copy the content below into intf_warn.xml
<interfaces xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-interface">
<interface>
<name>ce1/1</name>
<config>
<name>ce1/1</name>
<vrf-name>management</vrf-name>
</config>
<ipv4 xmlns="http://www.ipinfusion.com/yang/ocnos/ipi-if-ip">
<config>
<primary-ip-addr>100.12.23.3/24</primary-ip-addr>
</config>
</ipv4>
</interface>
</interfaces>
To receive warnings, NetConf client must subscribe to receive notifications.
yangcli ocnos@127.1> create-subscription
RPC OK Reply 3 for session 1:
Execute the following command and commit the changes:
yangcli ocnos@127.1> edit-config config=@/home/ocnos/intf_warn.xml
Filling container /edit-config/input/target:
RPC OK Reply 4 for session 1:
yangcli ocnos@127.1> commit
RPC OK Reply 6 for session 1:
Incoming notification:
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2021-07-07T14:03:39Z</eventTime>
<severity>info</severity>
<eventClass>config</eventClass>
<warning-notification xmlns="http://ipinfusion.com/ns/zebmcli">
<warningMsg>%% IP address removed due to enabling VRF management</warningMsg>
</warning-notification>
</notification>
Note: RFC 6241 is not detailed enough about how a NetConf server reports warnings. Therefore, OcNOS uses this warning reporting method.
Candidate Configuration store lock
Candidate configuration store is shared across all the NetConf clients. Client application must acquire lock if they want to provision the device without other client's hindrance
NetConf Client 1: locks candidate configuration store.
yangcli ocnos@127.1> lock target=candidate
RPC OK Reply 1 for session 4:
NetConf Client 2: attempts to acquire the lock now, which leads to an access-denied error.
yangcli ocnos@127.1> lock target=candidate
RPC Error Reply 1 for session 5:
rpc-reply {
rpc-error {
error-type protocol
error-tag lock-denied
error-severity error
error-app-tag no-access
error-message 'lock denied'
error-info {
session-id 0
error-number 268
}
}
}
Now error “access-denied” is received by NetConf client 2 when it attempts to provision the device.
yangcli ocnos@127.1> edit-config config=@/home/ospf_payload.xml
Filling list /ospfv2:
RPC Error Reply 3 for session 4:
rpc-reply {
rpc-error {
error-type application
error-tag in-use
error-severity error
error-app-tag no-access
error-path /nc:rpc/nc:edit-config/nc:config
error-message 'config locked'
error-info {
error-number 301
}
}
}
NetConf client 1 releases the lock
yangcli ocnos@127.1> unlock target=candidate
RPC OK Reply 2 for session 4:
NetConf client 2 can acquire the lock now, since no other client is holding the lock.
yangcli ocnos@127.1> lock target=candidate
RPC OK Reply 2 for session 5:
Startup configuration store lock
NetConf client 1 locks startup configuration store
yangcli ocnos@127.1> lock target=startup
RPC OK Reply 14 for session 4:
NetConf client 2 trying to modify the configuration store leads to error.
yangcli ocnos@127.1> copy-config source=running target=startup
RPC Error Reply 10 for session 5:
rpc-reply {
rpc-error {
error-type protocol
error-tag in-use
error-severity error
error-app-tag no-access
error-message 'config locked'
error-info {
error-number 301
}
}
}
Running configuration store lock
Running configuration lock handling across multiple NetConf clients is not supported. But across command line interface and NetConf clients is supported. Hence this section documentation is skipped for now.
Force unlock
Admin user has provision to forcibly release the lock held by other users on running configuration store. This command is not supported for candidate and startup configuration stores.
NetConf client 1 locks the running configuration store
yangcli ocnos@127.1> lock target=running
RPC OK Reply 6 for session 6:
Netconf client 2 tries to acquire running configuration store leads to an error.
yangcli ocnos@127.1> lock target=running
RPC Error Reply 21 for session 4:
rpc-reply {
rpc-error {
error-type protocol
error-tag lock-denied
error-severity error
error-app-tag no-access
error-message 'lock denied'
error-info {
session-id 6
error-number 268
}
}
}
NetConf client 2 (network-admin) decides to acquire the lock forcibly.
yangcli ocnos@127.1> force-unlock target=running
RPC OK Reply 22 for session 4:
yangcli ocnos@127.1> lock target=running
RPC OK Reply 23 for session 4:
Force unlock shall be issued with a timer value “after=<0-600> seconds” this command would inform existing lock holder about his lock expiry timeline.
Neconf client 2 (only network-admin) issues force-unlock command with a timer value of 60 seconds. Now after 60 seconds any other user is allowed to lock the running configuration store.
yangcli ocnos@127.1> force-unlock target=running after=60
RPC OK Reply 10 for session 6:
After 60 or more seconds, client shall issue lock command.
yangcli ocnos@127.1> lock target=running
RPC OK Reply 12 for session 6:
NetConf client 1 receives below notification about his lock expiry. To receive yangcli ocnos@127.1>
Incoming notification:
notification {
eventTime 2017-09-20T19:51:09Z
force_unlock {
message '% Session running config store lock will be released in 60 seconds'
}
}
Sys-reload
Use this RPC to cold restart the device.
Example:
yangcli ocnos@10.12.39.115> sys-reload
Enter boolean value for leaf <save-config>
yangcli ocnos@10.12.39.115:sys-reload>
false true
yangcli ocnos@10.12.39.115:sys-reload> true
RPC OK Reply 1 for session 4:
Sys-shutdown
Use this RPC to shut down the device.
Example:
yangcli ocnos@10.12.39.115> sys-shutdown
Enter boolean value for leaf <save-config>
yangcli ocnos@10.12.39.115:sys-shutdown>
false true
yangcli ocnos@..39.115:sys-shutdown>true