Sessions
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-pro implementation details which may NETCONF sessions.
User Names
The user name string associated with a NETCONF session is derived from the $SSH_CONNECTION environment variable, which is available to the netconf-subsystem-pro program when it is called by sshd.
Any user name accepted by sshd will be accepted by netconfd-pro.
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'].
Session ID
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.
Server <hello> Message
The netconfd-pro 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
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:
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:confirmed-commit:1.0</capability>
<capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability>
<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
<capability>urn:ietf:params:netconf:capability:url:1.0?scheme=file</capability>
<capability>urn:ietf:params:netconf:capability:xpath:1.0</capability>
<capability>urn:ietf:params:netconf:capability:notification:1.0</capability>
<capability>urn:ietf:params:netconf:capability:interleave:1.0</capability>
<capability>urn:ietf:params:netconf:capability:partial-lock:1.0</capability>
<capability>urn:ietf:params:netconf:capability:with-defaults:1.0?basic-mode=explicit&also-supported=trim,report-all,report-all-tagged</capability>
<capability>urn:yumaworks:params:xml:ns:netconf:config-id?id=127</capability>
<capability>urn:ietf:params:xml:ns:netconf:base:1.0?module=ietf-netconf&revision=2011-06-01&features=candidate,confirmed-commit,rollback-on-error,validate,url,xpath</capability>
<capability>urn:ietf:params:xml:ns:yang:iana-crypt-hash?module=iana-crypt-hash&revision=2014-08-06&features=crypt-hash-md5,crypt-hash-sha-256,crypt-hash-sha-512</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-acm?module=ietf-netconf-acm&revision=2018-02-14</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring?module=ietf-netconf-monitoring&revision=2010-10-04</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-notifications?module=ietf-netconf-notifications&revision=2012-02-06</capability>
<capability>urn:ietf:params:xml:ns:netconf:partial-lock:1.0?module=ietf-netconf-partial-lock&revision=2009-10-19</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults?module=ietf-netconf-with-defaults&revision=2011-06-01</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-restconf?module=ietf-restconf&revision=2017-01-26</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring?module=ietf-restconf-monitoring&revision=2017-01-26</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-yang-library?module=ietf-yang-library&revision=2016-06-21</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-yang-patch?module=ietf-yang-patch&revision=2017-02-22</capability>
<capability>urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2013-07-15</capability>
<capability>urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&revision=2008-07-14</capability>
<capability>urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&revision=2013-03-15</capability>
<capability>urn:ietf:params:xml:ns:yang:yang-data-ext?module=yang-data-ext&revision=2017-07-03</capability>
<capability>http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&revision=2017-07-25</capability>
<capability>http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&revision=2015-10-16</capability>
<capability>http://netconfcentral.org/ns/yuma-system?module=yuma-system&revision=2013-07-15</capability>
<capability>http://netconfcentral.org/ns/yuma-time-filter?module=yuma-time-filter&revision=2012-11-15</capability>
<capability>http://netconfcentral.org/ns/yuma-types?module=yuma-types&revision=2019-11-29</capability>
<capability>http://yumaworks.com/ns/yumaworks-app-common?module=yumaworks-app-common&revision=2019-05-22</capability>
<capability>http://yumaworks.com/ns/yumaworks-event-filter?module=yumaworks-event-filter&revision=2014-02-09</capability>
<capability>http://yumaworks.com/ns/yumaworks-extensions?module=yumaworks-extensions&revision=2019-01-04</capability>
<capability>http://yumaworks.com/ns/yumaworks-getbulk?module=yumaworks-getbulk&revision=2018-04-06</capability>
<capability>http://yumaworks.com/ns/yumaworks-ids?module=yumaworks-ids&revision=2014-07-12</capability>
<capability>urn:ietf:params:xml:ns:yang:yumaworks-restconf?module=yumaworks-restconf&revision=2017-07-03</capability>
<capability>urn:ietf:params:xml:ns:yang:yumaworks-support-save?module=yumaworks-support-save&revision=2017-07-27</capability>
<capability>http://yumaworks.com/ns/yumaworks-system?module=yumaworks-system&revision=2019-01-22</capability>
<capability>http://yumaworks.com/ns/yumaworks-templates?module=yumaworks-templates&revision=2017-02-20</capability>
<capability>http://yumaworks.com/ns/yumaworks-term-msg?module=yumaworks-term-msg&revision=2019-05-05</capability>
<capability>http://yumaworks.com/ns/yumaworks-types?module=yumaworks-types&revision=2018-05-03</capability>
<capability>urn:ietf:params:netconf:capability:yang-library:1.0?revision=2016-06-21&module-set-id=3783</capability>
</capabilities>
<session-id>3</session-id>
</hello>
Client <hello> Message
The netconfd-pro 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 may 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. By default, the server will enable both 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.
The following table shows the outcomes of all possible <hello> processing scenarios:
[ 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>
Note
If there are no common versions found, the session will be dropped.
RPC Request Processing
The only PDU the netconfd-pro 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 (:ref:
ietf-netconf-acm.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 a --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, then 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.
RPC Pipelining
RPC pipelining is supported, as specified in RFC 6241 Section 4.5. This feature refers to the ability for the server to receive new RPC requests on a session, while a current RPC operation is already in progress. The server will process the requests for this session in the order received.
Note
The client session TCP connection must not close until 'rpc-reply' messages have been received for all operations. This will cause the session processing to be terminated immediately, and any pending RPC requests for the session will be ignored.
Session Termination
A session can terminate for several reasons:
<close-session> operation invoked
<kill-session> operation invoked
SSH session terminated unexpectedly
TCP connection terminated unexpectedly
XML response to the client cannot be sent for any reason as specified in RFC 6241 Section 3
When a session terminates, the server does the following:
release any locks the session had (if any)
discard all changes in the <candidate> configuration, if this database was locked by the session.
remove the <session> list entry from the
/netconf-state/sessionscontainergenerate a <netconf-session-end> Event notification for the closed or killed session