Using NETCONF Sessions
The yangcli-pro program can be connected to up to 1000 NETCONF servers at a time.
Use the connect or start-session command to start a NETCONF session.
By default, a NETCONF over SSH session will be started.
Use the parameter 'transport=tls' in the connect command to start a NETCONF over TLS session.
When a NETCONF session starts up, a <capability> exchange is done, and the server reports exactly what content it supports. This information is used extensively to customize the session, and report errors and warnings for the session.
Connection Startup Screen
If the --log-level is set to 'info' or higher, then a startup screen will be displayed when a NETCONF session is started. It contains:
NETCONF session established for user on localhost
Client Session Id: 1
Server Session Id: 1
Server Protocol Capabilities
base:1.0
candidate:1.0
confirmed-commit:1.0
rollback-on-error:1.0
validate:1.0
url:1.0
xpath:1.0
notification:1.0
interleave:1.0
partial-lock:1.0
with-defaults:1.0
base:1.1
validate:1.1
confirmed-commit:1.1
yang-library:1.0
Server Module Capabilities
ietf-netconf@2011-06-01
ietf-inet-types@2013-07-15
ietf-netconf-acm@2012-02-22
ietf-netconf-monitoring@2010-10-04
ietf-netconf-notifications@2012-02-06
ietf-netconf-partial-lock@2009-10-19
ietf-netconf-with-defaults@2011-06-01
ietf-yang-library@2016-06-21
ietf-yang-types@2013-07-15
nc-notifications@2008-07-14
notifications@2013-03-15
yang-attributes@2013-02-18
yuma-app-common@2012-08-16
yuma-arp@2012-01-13
yuma-interfaces@2012-01-13
yuma-mysession@2013-10-05
yuma-ncx@2013-09-23
yuma-proc@2013-07-16
yuma-system@2013-07-15
yuma-time-filter@2012-11-15
yuma-types@2012-06-01
yumaworks-event-filter@2014-02-09
yumaworks-extensions@2014-06-05
yumaworks-ids@2014-07-12
yumaworks-sil-sa@2014-05-15
yumaworks-system@2014-05-27
yumaworks-types@2013-02-11
yumaworks-ycontrol@2014-04-08
Server Enterprise Capabilities
urn:yumaworks:params:xml:ns:netconf:config-id?id=7865
Protocol version set to: RFC 6241 (base:1.1)
Default target set to: <candidate>
Save operation mapped to: commit
Default with-defaults behavior: explicit
Additional with-defaults behavior: trim,report-all,report-all-tagged
Yang-Library set to: RFC 7895
module-set-id: 6765
Server Tailored Context
While a NETCONF session is active, the set of available YANG modules will be set to the modules that the server is using, if the --autoload configuration parameter is enabled.
If the schema-retrieval capability is also available on the server, then the <get-schema> operation will be attempted for any YANG module specified in the <hello> message capabilities, but not available to the yangcli-pro program.
When the server module capabilities are analyzed by the yangcli-pro client, the entire YANG module search path is checked for the specific module advertised in the capability. All the modules are partially parsed to check the actual namespace and revision date values. The following fields must exactly match in order for yangcli-pro to use a local YANG module, if --autoload=true.
module name
module revision date (if any)
module namespace
If the namespace URI value is different, it indicates that there is either a bug in one of the conflicting YANG modules, or that two different naming authorities picked the same module name. In this case, a warning will be generated during session initialization.
Any data returned from the server for YANG modules not currently available will be treated as a YANG 'anyxml' node, instead of the (unknown) YANG data type.
If the module contains YANG features that are not advertised in the <capabilities> exchange, then those data definitions will not be available (by default) for use in yangcli-pro commands.
If the module contains an object with a 'when' statement, and the 'when' XPath expression evaluates to 'false', then that data definition will not be available (by default) for use in yangcli-pro commands.
The help command will be tailored to the modules, capabilities, features, and module deviations reported by the server in <capability> exchange.
If --autoload-get is true, the <sget /netconf-state/schemas> operation will retrieve the /netconf-state/schemas sub-tree and the YANG sub-modules not known to yangcli-pro will be loaded correctly. If --autoload-get is false, then just the <hello> message module list will be used to retrieve YANG modules.
If --autoload-cache is true:
the YANG modules that are retrieved with the
sget /netconf-state/schemasoperation results will be cached. module can be used by yangcli-pro.the modules held in the YANG module cache are normally saved when yangcli-pro exits. If --autoload-save-cache is false, then the YANG modules that are cached will be not saved when yangcli-pro exits.
Retrieving Data
There are 8 commands available to retrieve generic data (i.e., an arbitrary subset of an entire NETCONF database):
Command |
Description |
|---|---|
raw NETCONF <get> operation |
|
raw NETCONF <get-config> operation |
|
raw NETCONF <get-data> operation |
|
high-level subtree filter, using the <get> protocol operation |
|
high-level subtree filter, using the <get-config> protocol operation |
|
high-level subtree filter, using the <get-data> protocol operation |
|
high-level XPath filter, using the <get> protocol operation |
|
high-level XPath filter, using the <get-config> protocol operation |
|
high-level XPath filter, using the <get-data> protocol operation |
All the high-level retrieval operations support the $$with-defaults system variable. The <with-defaults> parameter will be added to the NETCONF PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly.
session1> sget /system --with-defaults=$$with-defaults
This parameter can also be specified directly, each time the command is used.
session1> xget-config //ifMtu --with-defaults=trim
The $$bad-data system variable is used to control how invalid operations and data are sent to the server. The xget, xget-data, and xget-config commands are affected by this parameter.
If the :xpath capability was not advertised by the server when the session started, an error or warning may occur if these commands are used.
If any data is received that yangcli-pro does not understand, then a warning message will be printed and the data will be treated as if it was defined with the YANG 'anydata' node types.
Modifying Data
The following commands are available to modify generic data (i.e., an arbitrary subset of an entire NETCONF database):
Command |
Description |
|---|---|
raw NETCONF <commit> operation |
|
high-level <edit-config> operation, with nc:operation='create' |
|
high-level <edit-config> operation, with nc:operation='delete' |
|
raw NETCONF <delete-config> operation |
|
raw NETCONF <discard-changes> operation |
|
raw NETCONF <edit-config> operation |
|
fill a variable for re-use in other operations |
|
high-level <edit-config> operation, with YANG insert operation extensions |
|
lock a NETCONF database |
|
high-level <edit-config> operation, with nc:operation='merge' |
|
high-level <edit-config> operation, with nc:operation='replace' |
|
High level save operation, depending on the default target (candidate or running) |
|
unlock a NETCONF database |
All the high-level editing operations use the --target parameter reported by the server when the session started up. If the server did not report the :candidate or :writable-running capabilities, then there will be no writable target, and an error will occur if these commands are entered.
All the high-level editing operations support the $$default-operation system variable. The <default-operation> parameter will be added to the NETCONF <edit-config> PDU if this variable is set to a value other than 'not-used'. The default is the enumeration 'none', which means do not use any default operation, and only use the explicit 'nc:operation' attribute.
All the high-level editing operations support the $$test-option system variable. The <test-option> parameter will be added to the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly.
session1> replace /interfaces/interface[name='eth0']/ifMtu --test-option=$$test-option --value=$newvalue
This parameter can also be specified directly, each time the command is used.
session1> $newvalue = 1518
session1> replace /interfaces/interface[name='eth0']/ifMtu --test-option=test-only --value=$newvalue
All the high-level retrieval operations support the $$error-option system variable. The <error-option> parameter will be added to the NETCONF <edit-config> PDU if this variable is set to a value other than 'none' (the default). This system variable will be used as the default if not entered directly.
session1> replace /interfaces/interface[name='eth0']/ifMtu --error-option=$$error-option --value=1518
This parameter can also be specified directly, each time the command is used.
session1> replace /interfaces/interface[name='eth0']/ifMtu --error-option=rollback-on-error --value=1518
The high level save command is mapped to other commands, depending on the capabilities reported by the server. This command can be used instead of the multiple server variants of an "NV-save" operation.
save command
Capabilities |
Real Command(s) |
|---|---|
<none> |
|
copy-config --source=running --target=startup |
Using Notifications
The create-subscription command is used to start receiving notifications.
The netconfd-pro server will include a <sequence-id> element in any notification that is saved in the replay buffer. This unsigned integer can be used to help debug notification filters (i.e., if non-consecutive <sequence-id> values are received, then the notification was filtered, or dropped due to access control policy).
If any replay notifications are desired, then the 'startTime' parameter must be included. At the end of the stored notifications, the server will send the <replayComplete> Event. This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server. The netconfd-pro server will not include a <sequence-id> element in this notification type.
If the notification subscription should stop at a certain time, then the 'stopTime' parameter must be included. At the end of the stored notifications, the server will send the <replayComplete> Event, followed by the <notificationComplete> Event. This notification type is not saved, and will not be found in the server replay buffer, if replay is supported by the server. The netconfd-pro server will not include a <sequence-id> element in this notification type.
Notifications are printed to the log, using the current $$display-mode system variable setting, when and if they are received.
Notifications are also logged. Use the eventlog command to access the notifications stored in the event log.
Configuration Parameters That Affect Sessions
The --server, --user, and --password configuration parameters can be used to start a NETCONF session automatically at startup time. The connect command will only be attempted at startup time if the --server parameter is present.
If all 3 of these parameters are present at startup time, then no interactive prompting for additional optional parameters will be done. Instead the connect command will be invoked right away.
During normal operation, the --optional configuration parameter, or the $$optional system variable, can be used to control interactive prompting for optional parameters.
The --server parameter is saved in the $$server system variable, which can be overwritten at any time. If set, this will be used as the initial default value for this parameter in the connect command.
The --user parameter is saved in the $$user system variable, which can be overwritten at any time. If set, this will be used as the initial default value for this parameter in the connect command.
The $$with-defaults system variable can be used to set the default value for the 'with-defaults' parameter extension for these NETCONF operations:
The $$error-option system parameter, can be used to set the default value for the 'error-option' parameter for the NETCONF <edit-config> protocol operation. The default is 'none'.
The $$test-option system parameter can be used to set the default value for the 'test-option' parameter for the NETCONF <edit-config> protocol operation. The default is 'none'.
The --bad-data configuration parameter, or the $$bad-data system variable, can be used to control how yangcli-pro handles parameter values that are known to be invalid, or usage of optional protocol operations that the current session does not support.
The default value is 'check'. To use yangcli-pro in a testing mode to send the server incorrect data on purpose, set this parameter to 'warn' or 'ignore'.
Trouble-shooting NETCONF Session Problems
If the NETCONF session does not start for any reason, one or more error messages will be printed, and the prompt will indicate 'idle' mode. This section assumes that the server is netconfd-pro, and these debugging steps may not apply to all NETCONF agents.
If the NETCONF session does not start:
make sure the server is reachable
try to 'ping' the server and see if it responds
make sure the SSH server is responding
try to login in to the server using normal SSH login on port 22
make sure a firewall is not blocking TCP port 830
try to connect to the NETCONF server using the --port=22 option
make sure the netconf-subsystem is configured correctly in /etc/ssh/sshd_config there should be the proper configuration commands for NETCONF to work. For example, the netconfd-pro server configuration might look like this:
Port 22 Port 830 Subsystemnetconf/usr/sbin/netconf-subsystem
make sure the netconfd-pro server is running. Use the unix 'ps' command, or check the netconfd-pro log file, to make sure it is running.
ps -alx | grep netconf (look for 1 'netconfd-pro' and N 'netconf-subsystem' -- 1 for each active session)
make sure the user name is correct
This must be a valid user name on the system
make sure the password is correct
This must be the valid password (in /etc/passwd or /etc/shadow) for the specified user name
If the NETCONF session stops responding:
make sure the server is still reachable
try to 'ping' the server and see if it responds
make sure the SSH server is still responding
try to login in to the server using normal SSH login on port 22
If the NETCONF server is not accepting a certain command:
make sure the command (or parameters used in the command) is actually supported by the server.
There may be features, when statements, or deviation statements that indicate the server does not support the command or one or more of its parameters.
make sure that access control configured on the server is not blocking the command. The error-tag should be 'access-denied' in this case.
If the NETCONF server is not returning the expected data in a <get> or <get-config> protocol operation:
Make sure all the parameters are supported by the server
the :xpath capability must be advertised by the server to use the 'select' attribute in the <get> or <get-config> operations
the :with-defaults capability must be advertised by the server to use the <with-defaults> parameter
if using a filter, try to retrieve the data without a filter and see if it is there
make sure that access control configured on the server is not blocking the retrieval. There will not be any error reported in this case. The server will simply skip over any unauthorized data, and leave it out of the <rpc-reply>.
set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server. Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request.
If an <edit-config> operation is failing unexpectedly:
make sure that access control configured on the server is not blocking the request. The error-tag should be 'access-denied' in this case.
make sure an unsupported parameter or parameter value is not used
<test-option> is not supported unless the :validate capability is advertised by the server
<error-option> = 'rollback-on-error' is not supported unless the :rollback-on-error capability is advertised by the server
if the request contains an edit to a nested data structure, make sure the parent data structure(s) are in place as expected. The <default-operation> parameter is set to 'none' in the high level editing operations, so any data 'above' the edited data must already exist.
set the logging level to debug2 or higher, and look closely at the PDUs being sent to the server. Set the display mode to a value other than 'plain' to make sure the correct namespaces are being used in the request.