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/schemas operation 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

get

raw NETCONF <get> operation

get-config

raw NETCONF <get-config> operation

get-data

raw NETCONF <get-data> operation

sget

high-level subtree filter, using the <get> protocol operation

sget-config

high-level subtree filter, using the <get-config> protocol operation

sget-data

high-level subtree filter, using the <get-data> protocol operation

xget

high-level XPath filter, using the <get> protocol operation

xget-config

high-level XPath filter, using the <get-config> protocol operation

xget-data

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

commit

raw NETCONF <commit> operation

create

high-level <edit-config> operation, with nc:operation='create'

delete

high-level <edit-config> operation, with nc:operation='delete'

delete-config

raw NETCONF <delete-config> operation

discard-changes

raw NETCONF <discard-changes> operation

edit-config

raw NETCONF <edit-config> operation

fill

fill a variable for re-use in other operations

insert

high-level <edit-config> operation, with YANG insert operation extensions

lock

lock a NETCONF database

merge

high-level <edit-config> operation, with nc:operation='merge'

replace

high-level <edit-config> operation, with nc:operation='replace'

save

High level save operation, depending on the default target (candidate or running)

unlock

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)

:candidate

commit

:writable-running

<none>

:startup

copy-config --source=running --target=startup

Using Notifications

Notifications are not delivered automatically by the server. A subscription must be requested for the session, one of four ways:

  • Use the --autonotif='true' parameter setting to start receiving notifications automatically if they are available on the server.

  • Use the create-subscription command to start receiving notifications with an Old Dynamic Subscription (RFC 5277).

    • This legacy operation should not be used unless no other options exist.

    • Only one subscription per session is allowed if used.

    • No subscription ID assigned by the server

  • Use the establish-subscription command to start receiving notifications with a New Dynamic Subscription (RFC 8639)

    • This operation should be used if available.

    • Multiple subscriptions per session are allowed with this operation.

    • Subscription ID assigned by the server (can be used in other operations)

  • Starting in 23.10T-11, the subscribe command is available to subscribe to event streams and datastores. The server notification capabilities are examined and the best possible subscription type is used.

    • The 'subscribe stream' sub-command is used for event streams.

    • The 'subscribe data' sub-command is used for datastores (YANG Push RFC 8641)

Controlling Subscriptions

If Old Dynamic Subscriptions are used:

  • cancel-subscription may be available on the server to terminate the subscription on this session.

If New Dynamic Subscriptions are used:

  • configured notification filters can be stored in the /filters subtree and used instead of inline filters in the establish-subscription operation.

  • modify-subscription may be available on the server to terminate the subscription on this session.

  • delete-subscription may be available on the server to terminate the subscription on this session.

  • kill-subscription may be available on the server to terminate the subscription on any session.

  • Starting in 23.10T-11, the unsubscribe command is available to unsubscribe from event stream and datastore subscriptions.

Notification Replay

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.