Yuma netconfd Manual
YANG-Based Unified Modular Automation Tools
NETCONF Over SSH Server
Version 2.2
Last Updated: January 26, 2012
Table Of Contents
Yuma netconfd Manual
1 Preface 5
1.1 Legal Statements 5
1.2 Additional Resources 5
1.2.1 WEB Sites 5
1.2.2 Mailing Lists 6
1.3 Conventions Used in this Document 6
2 netconfd User Guide 7
2.1 Introduction 7
2.1.1 Features 7
2.1.2 Setting the Server Profile 9
2.1.3 Loading YANG Modules 9
2.1.4 Starting netconfd 10
2.1.5 Stopping netconfd 11
2.1.6 Signal Handling 11
2.1.7 Error Handling 11
2.1.8 Module Summary 12
2.1.9 Notification Summary 13
2.1.10 Operation Summary 14
2.1.11 Configuration Parameter List 15
2.2 Capabilities 17
2.2.1 :base:1.0 17
2.2.2 :base:1.1 17
2.2.3 :candidate 17
2.2.4 :confirmed-commit 17
2.2.5 :interleave 18
2.2.6 :netconf-monitoring 18
2.2.7 :notification 18
2.2.8 :partial-lock 18
2.2.9 :rollback-on-error 19
2.2.10 :schema-retrieval 19
2.2.11 :startup 19
2.2.12 :validate 19
2.2.13 :url 20
2.2.14 :with-defaults 21
2.2.15 :writable-running 21
2.2.16 :xpath 21
2.3 Databases 22
2.3.1 Database Locking 23
2.3.2 Using the <candidate> Database 23
2.3.3 Using the <running> Database 24
2.3.4 Using the <startup> Database 24
2.4 Sessions 24
2.4.1 User Names 24
2.4.2 Session ID 25
2.4.3 Server <hello> Message 25
2.4.4 Client <hello> Message 28
2.4.5 RPC Request Processing 28
2.4.6 Session Termination 29
2.5 Error Reporting 30
2.5.1 <error-severity> Element 30
2.5.2 <error-tag> Element 30
2.5.3 <error-app-tag> Element 31
2.5.4 <error-path> Element 32
2.5.5 <error-message> Element 33
2.5.6 <error-info> Element 33
2.5.7 instance-required Error Example 33
2.5.8 missing-choice Error Example 35
2.5.9 no-matches Error Example 36
2.5.10 not-in-range Error Example 38
2.6 Protocol Operations 39
2.6.1 <cancel-commit> 39
2.6.2 <close-session> 40
2.6.3 <commit> 41
2.6.4 <copy-config> 43
2.6.5 <create-subscription> 45
2.6.6 <delete-config> 47
2.6.7 <discard-changes> 48
2.6.8 <edit-config> 49
2.6.9 <get> 51
2.6.10 <get-config> 55
2.6.11 <get-my-session> 58
2.6.12 <get-schema> 59
2.6.13 <kill-session> 61
2.6.14 <load> 63
2.6.15 <lock> 64
2.6.16 <no-op> 66
2.6.17 <partial-lock> 67
2.6.18 <partial-unlock> 68
2.6.19 <restart> 70
2.6.20 <set-log-level> 70
2.6.21 <set-my-session> 72
2.6.22 <shutdown> 73
2.6.23 <unlock> 75
2.6.24 <validate> 76
2.7 Access Control 78
2.7.1 NACM Module Structure 79
2.7.2 Users and Groups 80
2.7.3 Creating New Groups 81
2.7.4 Access Control Modes 82
2.7.5 Permissions 82
2.7.6 Special YANG Extensions For Access Control 82
2.7.7 Default Enforcement Behavior 83
2.7.8 Access Control Algorithm 83
2.7.9 Module Access Control Rules 86
2.7.10 RPC Access Control Rules 87
2.7.11 Data Access Control Rules 88
2.8 Monitoring 90
2.8.1 Using Subtree Filters 90
2.8.2 Using XPath Filters 93
2.8.3 Using Time Filters 96
2.9 Notifications 97
2.9.1 Subscriptions 97
2.9.2 Notification Log 98
2.9.3 Using Notification Filters 98
2.9.4 <notification> Element 98
2.9.5 <replayComplete> Event 99
2.9.6 <notificationComplete> Event 99
2.9.7 <sysStartup> Event 100
2.9.8 <sysSessionStart> Event 101
2.9.9 <sysSessionEnd> Event 102
2.9.10 <sysConfigChange> Event 103
2.9.11 <sysCapabilityChange> Event 105
2.9.12 <sysConfirmedCommit> Event 107
3 CLI Reference 110
3.1 --audit-log 110
3.2 --audit-log-append 110
3.3 --access-control 110
3.4 --config 111
3.5 --datapath 112
3.6 --default-style 112
3.7 --delete-empty-npcontainers 113
3.8 --deviation 113
3.9 --eventlog-size 114
3.10 --feature-disable 114
3.11 --feature-enable 115
3.12 --feature-enable-default 116
3.13 --hello-timeout 116
3.14 --help 117
3.15 --help-mode 117
3.16 --idle-timeout 118
3.17 --indent 119
3.18 --log 119
3.19 --log-append 119
3.20 --log-level 120
3.21 --max-burst 121
3.22 --modpath 121
3.23 --module 122
3.24 --port 122
3.25 --protocols 122
3.26 --running-error 123
3.27 --runpath 123
3.28 --start 124
3.29 --startup-error 125
3.30 --subdirs 125
3.31 --superuser 126
3.32 --system-sorted 126
3.33 --target 126
3.34 --usexmlorder 127
3.35 --version 127
3.36 --warn-idlen 128
3.37 --warn-linelen 128
3.38 --warn-off 129
3.39 --with-startup 129
3.40 --with-url 130
3.41 --with-validate 130
3.42 --yuma-home 131
Copyright 2009 – 2012, Andy Bierman, All Rights Reserved.
This document assumes you have successfully set up the software as described in the printed document:
Yuma Installation Guide
Other documentation includes:
Yuma Quickstart Guide
Yuma User Manual
Yuma yangcli Manual
Yuma yangdiff Manual
Yuma yangdump Manual
Yuma Developer Manual
To obtain additional support you may join the yuma-users group on sourceforge.net and send email to this e-mail address:
yuma-users@lists.sourceforge.net
The SourceForge.net Support Page for Yuma can be found at this WEB page:
http://sourceforge.net/projects/yuma/support
There are several sources of free information and tools for use with YANG and/or NETCONF.
The following section lists the resources available at this time.
•Netconf Central
◦Yuma Home Page
▪Free information on NETCONF and YANG, tutorials, on-line YANG module validation and documentation database
•Yuma SourceFource OpenSource Project
◦http://sourceforge.net/projects/yuma/
▪Download Yuma source and binaries; project forums and help
•Yang Central
◦Free information and tutorials on YANG, free YANG tools for download
•NETCONF Working Group Wiki Page
◦Free information on NETCONF standardization activities and NETCONF implementations
•NETCONF WG Status Page
◦http://tools.ietf.org/wg/netconf/
◦IETF Internet draft status for NETCONF documents
•libsmi Home Page
◦Free tools such as smidump, to convert SMIv2 to YANG
•NETCONF Working Group
◦http://www.ietf.org/html.charters/netconf-charter.html
◦Technical issues related to the NETCONF protocol are discussed on the NETCONF WG mailing list. Refer to the instructions on the WEB page for joining the mailing list.
•NETMOD Working Group
◦Technical issues related to the YANG language and YANG data types are discussed on the NETMOD WG mailing list. Refer to the instructions on the WEB page for joining the mailing list.
The following formatting conventions are used throughout this document:
Documentation Conventions
Convention | Description |
--foo | CLI parameter foo |
<foo> | XML parameter foo |
foo | yangcli command or parameter |
$FOO | Environment variable FOO |
$$foo | yangcli global variable foo |
some text | Example command or PDU |
some text | Plain text |
netconfd Program Components
The netconfd program is a NETCONF-over-SSH server implementation. It is driven directly by YANG files, and provides a robust and secure database interface using standard NETCONF protocol operations.
All aspects of NETCONF protocol operation handling can be done automatically by the netconfd server. However, the interface between the NETCONF database and the device instrumentation is not covered in this document. Refer to the server Developers Guide for details on adding YANG module instrumentation code to the netconfd server.
The netconfd server has the following features:
•Complete implementation of NETCONF versions 1.0 and 1.1
•Automatic support for all NETCONF operations, including the YANG 'insert' operation.
•Supports <candidate>, <running>, and <startup> databases
•Supports the complete NETCONF protocol defined in RFC 4741 and RFC 6241.
•Supports the complete SSH transport binding defined in RFC 4742 and RFC 6242.
•Full, automatic run-time support for any YANG-defined NETCONF content:
◦rpc statement automatically supported, so new operations can be added at run-time
◦all YANG data statements automatically supported, so new database objects can be added at run-time
◦notification statement automatically supported, so new notification event types can be added at run-time
•Complete XML 1.0 implementation with full support for XML Namespaces
•Automatic support for all capability registration and <hello> message processing
•Full, automatic generation of all YANG module <capability> contents, including features and deviations
•Automatic session management, including unlimited number of concurrent sessions, session customization, and all database cleanup
•Fully recoverable, automatic database editing, using a simple 3 phase callback model
◦1) validate, 2) apply, 3) commit or rollback
•Full support for database locking, editing, validation, including extensive user-callback capabilities to support device instrumentation.
•Automatic support for all YANG validation mechanisms, including all XPath conditionals
•Automatic subtree and full XPath filtering
•Automatic confirmed-commit and rollback procedures
•Automatic database audit log and change notification support
•Complete <rpc-error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.
•Several <rpc-error> extensions, including <bad-value> and <error-number>, for easier debugging
•Comprehensive, fully NETCONF configurable, access control model, defined in yuma-nacm.yang.
•Complete RFC 5277 Notification support, including notification replay, :interleave capability, and several useful notifications implemented in yuma-system.yang.
•Complete RFC 5717 Partial Lock support with full XPath support, and all partial locking monitoring data defined in ietf-netconf-monitoring.yang.
•Full support for all YANG constructs, including deviations
•Full support of YANG sub-modules, including nested sub-modules
•Multiple concurrent module versions supported (import-by-revision)
•Multiple concurrent submodule versions supported (include-by-revision)
•Optimized, full XPath 1.0 implementation, including all YANG extensions
•Full implementation of the ietf-netconf-monitoring data model, including the
<get-schema> operation to retrieve YANG or YIN modules from the server.
•Configurable default node handling, including full support of the <with-defaults> standard, in ietf-with-defaults.yang.
•System information automatically supported, as defined in yuma-system.yang.
•Comprehensive logging capabilities for easy debugging during YANG content development or normal operation.
•Time filtering support for <get> and <get-config> requests with 'modified-since' and 'if-modified-since' per-datastore timestamps.
The netconfd server can behave in different ways, depending on the initial configuration parameters used.
The following parameters should be considered, and if the default behavior is not desired, then an explicit value should be provided instead:
•--yuma-home or $YUMA_HOME setting will affect YANG search path.
•--modpath or $YUMA_MODPATH setting will affect YANG search path.
•--datapath or $YUMA_DATAPATH setting will affect startup-cfg.xml search path.
•--target setting will select the edit target. The default is 'candidate', so this parameter must be set to choose 'running' as the edit target.
•--with-startup setting will enable the <startup> database if set to 'true'.
•--with-validate setting will enable the :validate capability if set to 'true'
•--access-control setting will affect how access control is enforced. The default is fully on ('enforcing').
•--superuser setting will affect access control, if it is enabled. The default is 'superuser'.
•--default-style setting will affect how default leaf values are returned in retrieval requests. The default is 'trim'. This returns everything except leafs containing the YANG default-stmt value, by default. To report every leaf value by default, set this parameter to 'report-all'. To report only leafs not set by the server by default, use the 'explicit' enumeration.
•--log and --log-level settings will affect how log messages are generated. The default is to send all messages to STDOUT, and use the 'info' logging level. If the server is a DEBUG image, then the default logging level will be 'debug' instead.
•--eventlog-size setting will control the memory used by the notification replay buffer
•--max-burst will control the of notifications sent at once to a single session
•--hello-timeout will control how long sessions can be stuck waiting for a hello message before they are dropped.
•-- idle-timeout will control how long active sessions can remain idle before they are dropped.
The --module parameter can be used from the CLI or .conf file to pre-load YANG modules and any related device instrumentation code into the server. A fatal error will occur if any module cannot be loaded, or it contains any YANG errors.
At run-time, the <load> operation (defined in yuma-system.yang) can be used to do the same thing, except the server will simply return an <rpc-error> instead of terminate, if the requested module cannot be loaded.
The current working directory in use when netconfd is invoked is important. It is most convenient to run netconfd in the background, and save all output to a log file.
The netconfd program listens for connection requests on a local socket, that is located in /tmp/ncxserver.sock.
In order for NETCONF sessions to be enabled, the SSH server and the netconf-subsystem programs must be properly installed first.
The netconfd program does not directly process the SSH protocol messages. Instead, it is implemented as an SSH subsystem. The number of concurrent SSH sessions that can connect to the netconfd server at once may be limited by the SSH server configuration. Refer to the Yuma Installation Guide for more details on configuring the SSH server for use with netconfd.
The netconfd program can be invoked several ways:
•To get the current version and exit:
netconfd --version
•To get program help and exit:
netconfd --help
netconfd --help --brief
netconfd --help --full
•To start the server in the background, set the loggin level to 'debug', and send logging messages to a log file
netconfd --log-level=debug --log=~/mylog &
•To start the server interactively, and send all log messages to STDOUT:
netconfd
•To start the server interactively, with a new log file:
netconfd --logfile=mylogfile
•To start the server interactively, and append to an existing log file:
netconfd --logfile=mylogfile --log-append
•To get parameters from a configuration file:
netconfd --config=/etc/yuma/netconfd.conf
To terminate the netconfd program when running interactively, use the control-C character sequence. This will cause the server to cleanup and terminate gracefully.
The <shutdown> or <restart> operations can also be used to terminate or restart the server. The yuma-nacm.yang access control rules must be configured to allow any user except the 'superuser' account to invoke this operation.
The server will respond to Unix signals sent to the netconfd process.
If the server is being run in the foreground, then the Control-C character sequence will perform the same action as a SIGINT signal.
Signals Recognized by netconfd
signal | number | description |
SIGHUP (Hangup) | 1 | Restart the server. |
SIGINT (Control-C) | 2 | Shutdown the server. |
SIGQUIT | 3 | Shutdown the server. |
SIGILL | 4 | Shutdown the server. |
SIGTRAP | 5 | Shutdown the server. |
SIGABRT | 6 | Shutdown the server. |
SIGKILL | 9 | Shutdown the server. |
SIGPIPE | 13 | Handle I/O connection error. |
SIGTERM | 15 | Shutdown the server. |
The kill command in Unix can be used to send signals to a process running in the background. Refer to the Unix man pages for more details.
All of the error handling requirements specified by the NETCONF protocol, and the YANG language error extensions for NETCONF, are supported automatically by netconfd.
There are 4 categories of error handling done by the server:
•incoming PDU validation
◦Errors for invalid PDU contents are reported immediately. The server will attempt to find all the errors in the input <rpc> request, and not stop detecting errors after one is found.
◦All machine-readable YANG statements are utilized to automate the detection and reporting of errors.
◦A node that is present, but has a false 'when' statement, is treated as an error.
•server instrumentation PDU validation
◦Semantic requirements expressed only in description statements will be checked by device instrumentation callbacks. The specific YANG data module should indicate which errors may be reported, and when they should be reported.
•database validation
◦Several automated tests are performed when a database is validated.
◦If the edit target is the <candidate> configuration, then referential integrity tests are postponed until the <commit> operation is attempted.
◦The specific conditions checked automatically are:
▪referential integrity condition test failed (must)
▪missing leaf (mandatory)
▪missing choice (mandatory)
▪extra container or leaf
▪too few instances of a list or leaf-list (min-elements)
▪too many instances of a list or leaf-list (max-elements)
▪instance not unique (unique)
◦Nodes that are unsupported by the server will automatically be removed from these tests. This can occur in the following ways:
▪node is defined within a feature that is not supported (if-feature)
▪node has conditional existence test that is false (when)
▪nodes derived from a 'uses' statement which has a conditional existence test that is false (when)
▪nodes derived from an 'augment' statement which has a conditional existence test that is false (when)
•server instrumentation database validation and activation
◦Errors can occur related to the specific YANG data model module, which can only be detected and reported by the server instrumentation.
◦Resource denied errors can occur while the server instrumentation is attempting to activate the networking features associated with some configuration parameters.
◦Instrumentation code can fail for a number of reasons, such as underlying hardware failure or removal.
The following YANG modules are built into the netconfd server, and cannot be loaded manually with the module parameter or <load> operation.
Pre-loaded YANG Modules
module | description |
ietf-inet-types | standard data types |
ietf-netconf-monitoring | standard NETCONF monitoring, and the <get-schema> operation |
ietf-netconf-partial-lock | standard NETCONF <partial-lock> and <partial-unlock> operations |
ietf-netconf-with-defaults | <with-defaults> extension |
ietf-yang-types | standard data types |
yuma-interfaces | network interfaces information |
yuma-nacm | NETCONF Access Control Model |
nc-notifications | standard replay notifications |
netconfd | Server CLI parameters |
notifications | standard notification operations |
yuma-arp | ARP configuration and monitoring |
yuma-ncx | Yuma NETCONF extensions |
yuma-app-common | Common CLI parameters |
yuma-types | Yuma common data types |
yuma-mysession | Get and Set session-specific parameters |
yuma-proc | /proc file system monitoriing |
yuma-system | system monitoring, operations, and notifications |
yuma-time-filter | Get only if datastore changed since a specified timestamp |
The following notification event types are built into the netconfd server:
Pre-loaded Notifications
module | event type | description |
nc-notifications | <replayComplete> | Notification replay has ended |
nc-notifications | <notificationComplete> | Notification delivery has ended |
yuma-system | <sysStartup> | server startup event |
yuma-system | <sysSessionStart> | NETCONF session started |
yuma-system | <sysSessionEnd> | NETCONF session ended |
yuma-system | <sysConfigChange> | <running> configuration has changed |
yuma-system | <sysCapabilityChange> | server capability added or deleted |
yuma-system | <sysConfirmedCommit> | confirmed-commit procedure event |
The following protocol operations are built into the netconfd server:
Pre-loaded Operations
module | operation | description |
Ietf-netconf | <cancel-commit> | Cancel a confirmed-commit operation. |
ietf-netconf | <close-session> | Terminate the current session. |
ietf-netconf | <commit> | Activate edits in <candidate>. |
ietf-netconf | <copy-config> | Copy an entire configuration. |
notifications | <create-subscription> | Start receiving notifications. |
ietf-netconf | <delete-config> | Delete a configuration. |
ietf-netconf | <discard-changes> | Discard edits in <candidate>. |
ietf-netconf | <edit-config> | Edit the target configuration. |
ietf-netconf | <get> | Retrieve <running> or state data. |
ietf-netconf | <get-config> | Retrieve all or part of a configuration. |
yuma-mysession | <get-my-session> | Retrieve session customization parameters. |
ietf-netconf-monitoring | <get-schema> | Retrieve a YANG or YIN module definition file. |
ietf-netconf | <kill-session> | Terminate a NETCONF session. |
netconfd | <load> | Load a YANG module. |
ietf-netconf | <lock> | Lock a database. |
netconfd | <no-op> | No operation. |
ietf-netconf-partial-lock | <partial-lock> | Lock part of the <running> database |
ietf-netconf-partial-lock | <partial-unlock> | Unlock part of the <running> database |
netconfd | <restart> | Restart the server. |
yuma-mysession | <set-my-session> | Set the session customization parameters. |
yuma-system | <set-log-level> | Set the logging verbosity level. |
netconfd | <shutdown> | Shutdown the server. |
ietf-netconf | <unlock> | Unlock a database. |
ietf-netconf | <validate> | Validate a database |
The following configuration parameters are used by netconfd. Refer to the CLI Reference for more details.
netconfd CLI Parameters
parameter | description |
--audit-log | Specifies the audit log of changes to the running database, after initial load is done. |
--audit-log-append | Append audit entryies to the existing log is present; Otherwise start a new audit log. |
--access-control | Specifies how access control will be enforced |
--config | Specifies the configuration file to use for parameters |
--datapath | Specifies the search path for the <startup> configuration file. |
--default-style | Specifies the default <with-defaults> behavior |
--delete-empty-npcontainers | Specifies that empty NP containers should be deleted or not |
--deviation | Species one or more YANG modules to load as deviations |
--eventlog-size | Specifies the maximum number of events stored in the notification replay buffer. |
--feature-disable | Leaf list of features to disable |
--feature-enable | Specifies a feature that should be enabled |
--feature-enable-default | Specifies if a feature should be enabled or disabled by default |
--help | Get context-sensitive help with --brief or --full extension |
--hello-timeout | Set the number of seconds to wait for a <hello> PDU |
--idle-timeout | Set the number of seconds to wait for a <rpc> PDU |
--indent | Specifies the indent count to use when writing data |
--log | Specifies the log file to use instead of STDOUT |
--log-append | Controls whether a log file will be reused or overwritten |
--log-level | Controls the verbosity of logging messages |
--max-burst | Specifies the maximum number of notifications to send to one session in a row. |
--modpath | Sets the module search path |
--module | Specifies one or more YANG modules to load upon startup |
--protocols | Specifies which NETCONF protocol versions to enable |
--no-startup | If present, the startup configuration will not be used (if present), and the factory defaults will be used instead. |
--port | Specifies up to 4 TCP port numbers to accept NETCONF connections from |
--runpath | Server instrumentation library (SIL) search path |
--running-error | Specifies whether the server should stop or continue if the running configuration contains any errors at boot-time (such as missing mandatory nodes) |
--startup | Specifies the startup configuration file location to override the default. Not allowed if the --no-startup parameter is present. |
--startup-error | Specifies whether the server should stop or continue if the startup configuration contains any recoverable errors (the bad configuration data can be removed) |
--subdirs | If true, then sub-directories will be searched when looking for files. Otherwise just the specified directory will be used and none of its sub-directories (if any). |
--superuser | Specifies the user name (or empty string for none) to be given super user privileges, instead of the default 'superuser'. |
--system-sorted | Specifies whether system ordered lists and leaf-lists should be maintained in sorted order |
--target | Specifies if the <candidate> or <running> configuration should be the edit target |
--usexmlorder | Forces strict YANG XML ordering to be enforced |
--version | Prints the program version and exits |
--warn-idlen | Controls how identifier lengths are checked |
--warn-linelen | Controls how line lengths are checked |
--warn-off | Suppresses the specified warning number |
--with-startup | Enable or disable the <startup> database |
--with-url | Enable or disable the :url capability |
--with-validate | Enable or disable the :validate capability |
--yuma-home | Specifies the $YUMA_HOME project root to use when searching for files |
Server capabilities are the primary mechanism to specify optional behavior in the NETCONF protocol. This section describes the capabilities that are supported by the netconfd server.
The :base:1.0 capability indicates that the RFC 4741 version of the NETCONF protocol is supported.
This capability can be controlled with the –protocols CLI parameter.
This capability is supported by default.
The :base:1.1 capability indicates that the RFC 6241 version of the NETCONF protocol is supported.
This capability can be controlled with the –protocols CLI parameter.
This capability is supported by default.
The :candidate capability indicates that database edits will be done to the <candidate> database, and saved with the <commit> operation.
The <candidate> configuration is a shared scratch-pad, so it should be used with the locking. Database edits are collected in the <candidate> and then applied, all or nothing, to the <running> database, with the <commit> operation.
This capability is supported by default. It is controlled by the --target configuration parameter (--target=candidate).
By default, only the superuser account can use the <delete-config> operation on the <candidate> configuration.
The :confirmed-commit capability indicates that the server will support the <confirmed> and <confirm-timeout> parameters to the <commit> operation. If the 'base:1.1' protocol version is in use, then the <persist> and <persist-id> parameters are also supported.
The confirmed commit procedure requires that two <commit> operations be used to apply changes from the candidate configuration to the running configuration.
If the second <commit> operation is not received before the <confirm-timeout> value (default 10 minutes), then the running and candidate configurations will be reset to the contents of the running configuration, before the first <commit> operation.
If the session that started the confirmed-commit procedure is terminated for any reason before the second <commit> operation is completed, then the running configuration will be reset, as if the confirm-timeout interval had expired.
If the confirmed-commit procedure is used, and the :startup capability is also supported, then the contents of NV-storage (e.g., startup-cfg.xml) will not be updated or altered by this procedure. Only the running configuration will be affected by the rollback,
If the <confirmed> parameter is used again, in the second <commit> operation, then the timeout interval will be extended, and any changes made to the candidate configuration will be committed. If the running and candidate configurations are reverted, any intermediate edits made since the first <commit> operation will be lost.
The :interleave capability indicates that the server will accept <rpc> requests other than <close-session> during notification delivery. It is supported at all times, and cannot be configured.
The :netconf-monitoring capability indicates that the /ietf-netconf-monitoring data sub-tree is supported.
The netconfd server supports all of the tables in this module, except partial-locking, because the :partial-lock capability is not supported at this time.
The /netconf-state/capabilities subtree can be examined to discover the active set of NETCONF capabilities.
The /netconf-state/datastores subtree can be examined to discover the active database locks.
The /netconf-state/schemas subtree can be examined for all the YANG modules that are available for download with the <get-schema> operation.
The /netconf-state/sessions subtree can be examined for monitoring NETCONF session activity.
The /netconf-state/statistics subtree can be examined for monitoring global NETCONF counters.
The :notification capability indicates that the server will accept the <create-subscription> operation, and deliver notifications to the session, according to the subscription request.
All <create-subscription> options and features are supported.
A notification log is maintained on the server, which is restarted every time the server reboots.
This log can be accessed as a 'replay subscription'.
The first notification in the log will be for the <sysStartup> event.
The <replayComplete> and <notificationComplete> event types are not stored in the log.
The :partial-lock capability indicates that RFC 5717 is implemented, and partial locking of the <running> database is supported.
The <copy-config> operation is not supported using the <running> database as a target, so partial locks do not affect that operation.
The <edit-config> operation on the <running> database is allowed if the --target parameter is set to 'running'.
The <commit> operation will fail if any portion of the altered configuration is locked by another session. Data in the <candidate> database which is identical to the corresponding data in the <running> configuration is not affected by a <partial-lock> operation.
The constant VAL_MAX_PLOCKS in ncx/val.h controls the maximum number of concurrent locks that a single session can own on a database node. The default value is 4.
There is no hard resource limit for:
•the number of total partial-locks
•the number of <select> parameters in the <partial-lock> request
•the number of nodes that can be locked by a single partial-lock
When the maximum <lock-id> is reached (MAX_UINT), the server will not reset the <lock-id> to '1' unless there are no partial locks currently held on the <running> database. The <lock-id> '0' is not used.
The :rollback-on-error capability indicates that the server supports 'all-or-nothing' editing for a single <edit-config> operation. This is a standard enumeration value for the <error-option> parameter.
The server will perform all PDU validation no matter what <error-option> is selected.
Execution phase will not occur if any errors at all are found in the validation phase.
During execution phase, this parameter will affect error processing. When set to rollback-on-error, if any part of the requested configuration change cannot be performed, the database will be restored to its previous state, and server instrumentation callbacks to 'undo' any changes made will be invoked.
The :schema-retrieval capability indicates that the <get-schema> operation is supported.
The netconfd server supports this operation for all YANG modules in use at the time.
The <identifier> parameter must be set to the name of the YANG module.
The <format> parameter must be set to 'YANG'.
The <version> parameter must be set to a revision date to retrieve a specific version of the module, or the empty string to retrieve whatever version the server is using.
The :startup capability indicates that the <startup> configuration is supported by the server.
By default, this capability is not supported.
This capability is controlled by the --with-startup configuration parameter. If this parameter is set to 'true', then the :startup capability will be supported.
If this capability is supported:
•the server will allow the <startup> configuration to be the source of a <get-config>.
•the server will allow the <startup> configuration to be the target of a <copy-config> operation, if the source is the <running> configuration.
•If the :validate capability is enabled, then the server will allow the <startup> configuration to be the target of a <validate> operation.
•If the user is the super user account, or access is configured in NACM to allow it, then the server will allow the <startup> configuration to be the target of a <delete-config> operation.
No other operations on the <startup> database are supported. The <startup> database cannot be edited with <edit-config>, or over-written with <copy-config>.
The :validate capability indicates that the <validate> operation is accepted, and the <test-option> for the <edit-config> operation is also accepted, by the server.
Versions supported:
•validate:1.0
•validate:1.1
This capability is controlled by the --with-validate configuration parameter. If it is set to 'false' then this capability will not be available in netconfd.
The <validate> operation can be invoked in several ways:
•validate the <candidate> database if the :candidate capability is supported
•validate the <running> database
•validate the <startup> database if the :startup capability is supported
•validate an inline <config> element, which represents the entire contents of a database.
The <test-option> parameter for the <edit-config> operation can be used. This parameter has a significant impact on operations, and needs to be used carefully.
•set: This option is not the default, but it is probably the desired behavior for the <candidate> database. In order to fully utilize the incremental editing capability of this database, the 'set' value should be used. This will prevent any validation error messages unrelated to the current edit. The <validate> operation can be used before the <commit> is done, if desired. The same errors (if any) should be reported by <validate> or <commit>.
•test-then-set: This option is the default, and will cause a resource intensive validation procedure to be invoked every time the <candidate> database is edited. (The validation procedure is always invoked on every edit to the <running> configuration.) If any database validation errors are found (in addition to the requested edit), then they will be reported. Use the <error-path> field to determine which type of error is being reported by the server.
The :url capability indicates that the server accepts the <url> parameter in NETCONF operations that use this parameter. This capability can be disabled with the --with-url CLI configuration parameter.
The following operations are affected by the :url capability:
•edit-config
◦<url> accepted instead of <config> as a configuration data source
•copy-config
◦<url> accepted as a source parameter.
◦<url> accepted as a target paramter.
◦<url> to <url> copy not supported (optional to implement)
•delete-config:
◦<url> accepted as source to delete
•validate
◦<url> accepted as a configuration source to validate.
Only the 'file' scheme is supported at this time.
A URL file can be specified as a simple file within the root directory.
No whitespace or special characters are allowed in the file name.
The file extension '.xml' should be used. The server only generates and expects XML configuration files. The NETCONF 'config' element is used as the top-level element in all <url> files.
The $YUMA_DATAPATH environment variable or the $$datapth system variable is used to find the file names specified in the <url> URI string.
Example:
<url>file:///my-backup.xml</url>
The :with-defaults capability indicates that the server will accept the <with-defaults> parameter for the following operations:
•<get>
•<get-config>
•<copy-config>
There are 4 values defined for this parameter. The server supports all of them, no matter what mode is used for the default style.
•report-all: all nodes are reported
•report-all-tagged: all nodes are reported with an XML attribute indicating the nodes which are considered default nodes by the server.
•trim: nodes set to thier YANG default-stmt value by the server or the client are skipped
•explicit: nodes set by the server are skipped. (Nodes set in the <startup> are considered to be set by the client, not the server.)
The --default-style configuration parameter is used to control the behavior the server will use for these operations when the <with-defaults> parameter is missing. The server will also use this default value when automatically saving the <running> configuration to non-volatile storage.
The :writable-running capability indicates that the server uses the <running> configuration as its edit target. In this case, the <target> parameter for the <edit-config> operation can only be set to <running/>.
All edits are activated immediately, but only if the entire database is going to be valid after the edits. A non-destructive test is performed before activating the requested changes.
If this capability is advertised, then netconfd will also advertise the :startup capability. They are always used together.
Edits to the <running> configuration take affect right away, but they are only saved to non-volatile storage automatically if the with-startup configuration parameter is set to 'false'.
The :xpath capability indicates that XPath filtering is supported for the <get> and <get-config> operations.
The netconfd server implements all of XPath 1.0, plus the following additions:
•the current() function from XPath 2.0 is supported
•a missing XML namespace will match any YANG module namespace (XPath 2.0 behavior) instead of matching the NULL namespace (XPath 1.0 behavior)
•the 'preceding' and 'following' axes should not be used. The database is dynamic and the relative document order is not stable. This is also a very resource intensive operation.
XPath filtering affects whether the server will return particular subtrees or not. It does not change the format of the <get> or <get-config> output. The result returned by the server will not be the raw XPath node-set from evaluating the specified 'select' expression against a database.
The server will normalize the XPath search results it returns:
•There will be no duplicate nodes, even if there were duplicates in the XPath result node-set.
•All result nodes with common ancestor nodes will be grouped together in the <rpc-reply>.
•All list nodes will include child nodes for any missing key leafs, even if they were not requested in the 'select' expression.
A NETCONF database is conceptually represented as an XML instance document.
There are 3 conceptual databases, which all share the exact same structure.
•<candidate>: scratch-pad to gather edits to apply to <running> all at once
•<running>: configuration data in effect
•<startup>: configuration data for the next reboot
When the <running> configuration is saved to non-volatile storage, the top-level element of this document is the <config> container element.
The XML namespace of this element is the netconfd module namespace, but a client application should expect that other server implementations may use a different namespace, such as the NETCONF namespace, or perhaps no namespace at all for this top-level element.
When database contents are returned in the <get>, <get-config>, or <copy-config> operations, the top-level container will be the <data> element in the NETCONF base namespace.
The top-level YANG module data structures that are present in the configuration will be present as child nodes of the <config> or <data> container node.
The exact databases that are present in the server are controlled by 3 capabilities:
•:candidate
•:writable-running
•:startup
The edit target in the server is set with the --target configuration parameter. This will select either the :candidate or :writable-running capabilities.
The server behavior for non-volatile storage of the <running> configuration is set with the
--with-startup configuration parameter. The :startup capability will be supported if this parameter is set to 'true'.
The following diagram shows the 4 database usage modes that netconfd supports:
It is strongly suggested that the <lock> and <unlock> operations be used whenever a database is being edited. All the databases on the server should be locked, not just one, because different operations are controlled by different locks. The only way to insure that the entire database transaction is done in isolation is to keep all the databases locked during the entire transaction.
The affected configurations should be locked during the entire transaction, and not released until the edits have been saved in non-volatile storage.
If the edit target is the <candidate> configuration, then the <candidate> and <running> configurations should be locked.
If the edit target is the <running> configuration, then the <running> and <startup> configurations should be locked.
Whenever the lock on the <candidate> configuration is released, a <discard-changes> operation is performed by the server. This is required by the NETCONF protocol.
Of the <candidate> configuration contains any edits, then a lock will fail with a 'resource-denied' error. In this case, a lock on the <candidate> configuration cannot be granted until the <discard-changes> operation is completed.
The <candidate> database is available if the :candidate capability is advertised by the server.
The <lock> operation will fail on this database if there are any edits already pending in the <candidate>. If a 'lock-failed' error occurs and no session is holding a lock, then use the <discard-changes> operation to clear the <candidate> buffer of any edits.
Once all the edits have been made, the <validate> operation can be used to check if all database validation tests will pass. This step is optional.
Once the edits are completed, the <commit> operation is used to activate the configuration changes, and save them in non-volatile storage.
The <discard-changes> operation is used to clear any edits from this database.
The <running> database is available at all times for reading.
If the :writable-running capability is advertised by the server, then this database will be available as the target for <edit-config> operations.
Edits to the <running> configuration will take affect right away, as each <edit-config> operation is completed.
Once all the edits are completed, the <copy-config> operation can be used to save the current <running> configuration to non-volatile storage, by setting the target of the <copy-config> operation to the <startup> configuration.
The <startup> database is available if the :startup capability is advertised by the server.
The <copy-config> operation can be used to save the contents of the <running> configuration to the <startup> configuration.
The <get-config> operation can be used to retrieve the contents of the <startup> configuration.
The <delete-config> operation can be used to delete the <startup> configuration. Only the superuser account is allowed to do this, by default.
All NETCONF server access is done through the NETCONF protocol, except the server can be shutdown with the Control-C character sequence if it being run interactively.
This section describes any netconfd implementation details which may NETCONF sessions.
The user name string associated with a NETCONF session is derived from the $SSH_CONNECTION environment variable, which is available to the netconf-subsystem program when it is called by sshd.
Any user name accepted by sshd will be accepted by netconfd.
In order for access control to work properly, the sshd user name must also conform to the NacmUserName type definition:
typedef NacmUserName {
description "General Purpose User Name string.";
type string {
length "1..63";
pattern '[a-z,A-Z][a-z,A-Z,0-9]{0,62}';
}
}
•A user name cane be 1 to 63 characters long.
•The first character must be a letter ['a' to 'z', or 'A' to 'Z']
•The remaining characters must be a letter ['a' to 'z', or 'A' to 'Z'], or a number
['0' to '9'].
The <session-id> assigned by the server is simply a monotonically increasing number:
typedef SessionId {
description "NETCONF Session Id";
type uint32 {
range "1..max";
}
}
The server will start using session ID values over again at 1, if the maximum session-id value is ever reached.
The netconfd server will send a <hello> message if a valid SSH2 session to the netconf subsystem is established.
The server will list all the capabilities it supports.
The YANG module capability URI format is supported for all modules, including ones that only contain typedefs or groupings.
The URI format is defined in the YANG specification, and follows this format:
<module-namespace> '?module='<module-name>'&revision='<module-date>'
If the module does not have any revision statements, then the revision field will not be present in the module capability URI.
If the module contains any supported features, then the following field will be added, and each supported feature name will be listed:
'&features='<feature-name> [','<feature-name>]*
If the module needs any external deviations applied, then the following field will be added, and each deviation module name will be listed:
'&deviations='<deviation-module-name> [','<deviation-module-name>]*
Note that the deviation modules will be listed in the capabilities, along with other modules. The 'deviations' extension allows a client tool to know that the deviations apply to the specific module, since special processing may be required.
Example server <hello> Message:
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<nc:capabilities>
<nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:candidate:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:confirmed-commit:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:rollback-on-error:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:validate:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:xpath:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:notification:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:interleave:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:with-defaults:1.0?basic=explicit&supported=report-all:trim
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:netconf-monitoring:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:schema-retrieval:1.0
</nc:capability>
<nc:capability>
urn:ietf:params:xml:ns:yang:inet-types?module=ietf-inet-types&revision=2009-05-13
</nc:capability>
<nc:capability>
urn:ietf:params:xml:ns:netconf:monitoring?module=ietf-netconf-monitoring&revision=2009-06-16
</nc:capability>
<nc:capability>
urn:ietf:params:netconf:capability:with-defaults:1.0?module=ietf-with-defaults&revision=2009-07-01&features=with-defaults
</nc:capability>
<nc:capability>
urn:ietf:params:xml:ns:yang:yang-types?module=ietf-yang-types&revision=2009-05-13
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-interfaces?module=interfaces&rQ
ses_msg: setup send buff 1
evision=2009-07-17
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-mysession?module=yuma-mysession&revision=2009-08-11
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-nacm?module=yuma-nacm&revision=2009-05-13
</nc:capability>
<nc:capability>
urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&revision=2008-07-14
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&revision=2009-06-12
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&revision=2009-04-10
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-types?module=yuma-types&revision=2008-07-20
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/netconfd?module=netconfd&revision=2009-05-28
</nc:capability>
<nc:capability>
urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&revision=2008-07-14
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-proc?module=yuma-proc&revision=2009-07-17
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/yuma-system?module=yuma-system&revision=2009-06-04
</nc:capability>
<nc:capability>
http://netconfcentral.org/ns/test?module=test&revision=2009-06-10&features=feature1,feature3,feature4
</nc:capability>
</nc:capabilities>
<nc:session-id>1</nc:session-id>
</nc:hello>]]>]]>
The netconfd server requires a valid <hello> message from the client before accepting any <rpc> requests.
Only the mandatory 'netconf base' URIs will be checked by the server. All other <capability> elements will be ignored by the server.
The server can be configured with the –protocols CLI parameter to enable the 'base:1.0', and/or the 'base:1.1' NETCONF protocol versions. Both the client and server send the 'base:1.x' (where 'x' is '1' or '2') URIs they support (1 or 2 <capability> elements). The highest version in common determines the protocol version used for the session. If there are no common versions found, the session will be dropped. By default, the server will enable both protocol versions.
The following table shows the outcomes of all possible <hello> processing scenarios:
Client <hello> | Server <hello> | Outcome |
[ none ] | [ any combination ] | Session dropped |
[ base:1.0 ] | [ base:1.0 ] | base:1.0 session started |
[ base:1.1 ] | [ base:1.0 ] | Session dropped |
[ base:1.0 base:1.1] | [ base:1.0 ] | base:1.0 session started |
[ base:1.0 ] | [ base:1.1 ] | Session dropped |
[ base:1.1 ] | [ base:1.1 ] | base:1.1 session started |
[ base:1.0 base:1.1] | [ base:1.1 ] | base:1.1 session started |
[ base:1.0 ] | [ base:1.0 base:1.1 ] | base:1.0 session started |
[ base:1.1 ] | [ base:1.0 base:1.1 ] | base:1.1 session started |
[ base:1.0 base:1.1] | [ base:1.0 base:1.1 ] | base:1.1 session started |
Example client <hello> Message:
<?xml version="1.0" encoding="UTF-8"?>
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
<nc:capabilities>
<nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
</nc:capabilities>
</nc:hello>
The only PDU the netconfd server will accept during a NETCONF session is the <rpc> message.
All aspects of NETCONF protocol conformance are supported for contents of the <rpc> elements:
•All XML attributes in the <rpc> start tag will be returned to the client (unchanged) in the <rpc-reply> element. The order of the XML attributes may not be preserved.
•All XML namespace prefix assignments declared in the <rpc> element (via the 'xmlns' attribute) will be used within the <rpc-reply>, and most descendant nodes of the <rpc-reply. The exception is the <error-path> element, which may use the default XML prefix for a given module, by declaring a new xmlns attribute for the namespace.
•The so-called mandatory 'message-id' attribute is ignored by the server, along will all other XML attributes in the <rpc> element. The server will not generate an error if this attribute is missing, as specified in RFC 4741. The new version of the NETCONF protocol removes this rule.
All <rpc> element contents must be declared within the proper namespace, except the contents of a subtree <filter> element for a <get> or <get-config> operation.
Access control will be enforced as follows:
•All <rpc> operation requests except <close-session> will be checked in the access control model (yuma-nacm.yang). This operation can always be invoked by any user, to allow graceful session termination in all cases.
•If the user name for the session matches the --superuser configuration parameter, then the operation will always be allowed.
•If the access control 'no-rule' default for RPC execution is set to 'permit', and there is no access control rule found to match the current <rpc> request, the the operation will always be allowed. The default for this parameter is 'permit'.
•If a matching access control rule is found, execution access will be permitted or denied, based on the specific rule. (I.e., 'exec' privilege bit set or not).
•If the operation reads or writes any database data, then the access control model will be checked again, for each database node specified in the request.
◦If the operation is requesting read access, then any nodes for which read permission is not granted will simply be skipped in the result. No error or warning will be reported.
◦If the operation is requesting write access, then any nodes for which write permission is not granted will cause an 'access-denied' error.
The server does not generate inline <rpc-error> elements at this time, for any runtime exceptions that occur while retrieving data for a <get>, <get-config>, or <copy-config> operation. Instead, unavailable nodes are just skipped.
A future version will support this feature, so managers should expect that <rpc-error> might appear within the data in a reply, not just a child node of the <rpc-reply> element.
A session can terminate for several reasons:
•<close-session> operation invoked
•<kill-session> operation invoked
•SSH session terminated unexpectedly
•TCP connection terminated unexpectedly
When a session terminates, the server does the following:
•will release any locks the session had (if any)
•will discard all changes in the <candidate> configuration, if this database was locked by the session.
•will remove the <session> list entry from the /netconf-state/sessions container
•will generate a <sysSessionEnd> notification entry for the closed or killed session
All errors are reported using the standard <rpc-error> element.
If the operation does not return any data, then the <rpc-reply> element will either contain 1 <ok/> element, or 1 or more <rpc-error> elements.
If the operation returns any data (i.e., the YANG rpc definition for the operation has an 'output' section), then the <rpc-reply> element may have both <rpc-error> and data elements within it. If there were errors in the input, then only 1 or more <rpc-error> elements will be returned. It is possible that the required data will be returned, after any errors, but not likely.
The internal netconfd error code for each <rpc-error> is returned in an <error-info> extension called <error-number>.
Normally, the same <error-app-tag> and <error-message> values are returned for a specific error number. However, some YANG errors allow these fields to be user-defined. If there is a user-defined <error-app-tag> and/or <error-message> values, then they will be used instead of the default values.
This section describes the netconfd implementation details which may affect <rpc-error> processing by a client application.
The <error-severity> field will always be set to 'error'. There are no warnings generated by netconfd.
All NETCONF <error-tag> enumerations are supported, except 'partial-operation'. This error is being deprecated in the standard because nobody has implemented it.
If this field is set to 'invalid-value', then the <bad-value> element should be present in the <error-info>, identifying the invalid value that caused the problem.
All standard <error-info> contents are supported. The following table summarizes the different <error-tag> values. The <error-number> parameter is not shown in the 'error-info' column because it is added for every error-tag.
<error-tag> Summary
error-tag | error-info | description |
access-denied | none | NACM denied access |
bad-attribute | <bad-attribute> | just for the few attributes used in NETCONF |
bad-element | <bad-element> | sometimes used instead of invalid-value |
data-exists | none | nc:operation='create' |
data-missing | none | nc:operation='delete' or |
in-use | none | edit on locked database |
invalid-value | <bad-value> | for typedef constraints |
lock-denied | <session-id> | for <lock> only |
missing-attribute | <bad-attribute> | just for the few attributes used in NETCONF |
missing-element | <bad-element> | mandatory parameters |
operation-not-supported | none | unsupported, false |
operation-failed | none | when no other error-tag applies |
partial-operation | <ok-element> | not implemented |
resource-denied | none | malloc failed |
rollback-failed | none | rollback-on-error failed |
too-big | none | input too big to buffer |
unknown-attribute | <bad-attribute> | for any non-NETCONF attributes found |
unknown-element | <bad-element> | wrong element name in a known namespace |
unknown-namespace | <bad-element> | module not loaded |
malformed-message | None | base:1.1 framing lost in transport layer |
The <error-app-tag> field provided a more specific error classification than the <error-tag> field. It is included in every <rpc-error> response.
This field is encoded as a simple string.
It is possible that error-app-tag values from different vendors will use the same string. A client application needs to account for this shared namespace.
If the YANG 'error-app-tag' statement is defined for the specific error that occured, then it will be used instead of the default value.
The following table describes the default <error-app-tag> values used by netconfd:
<error-app-tag> Summary
error-app-tag | description |
data-incomplete | the input parameters are incomplete |
data-invalid | one or more input parameters are invalid |
data-not-unique | unique statement violation (YANG, sec. 13.1) |
duplicate-error | trying to create a duplicate list or leaf-list entry |
general-error | no other description fits |
instance-required | missing mandatory node (YANG, sec. 13.5) |
internal-error | internal software error |
io-error | NETCONF session IO error |
libxml2-error | libxml2 internal error or parsing error |
limit-reached | some sort of defined limit was reached |
malloc-error | malloc function call failed |
missing-choice | mandatory choice not found (YANG, sec. 13.6) |
missing-instance | mandatory leaf not found (YANG, sec. 13.7) |