<center>'''Yuma netconfd Manual'''</center>


<center>YANG-Based Unified Modular Automation Tools</center>


<center>NETCONF Over SSH Server</center>


<center>Version yuma123-2.10</center>

= Preface =
== Legal Statements ==
Copyright 2009 – 2012, Andy Bierman, All Rights Reserved.

Copyright 2013 – 2017, Vladimir Vassilev, All Rights Reserved.

== Additional Resources ==
This document assumes you have successfully set up the software as
described in the printed document:

[[Yuma Installation Guide]]

Other documentation includes:

[[Yuma User Manual]]

[[Yuma yangcli Manual]]

[[Yuma yangdiff Manual]]

[[Yuma yangdump Manual]]

[[Yuma Developer Manual]]

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.

=== WEB Sites ===
* '''Netconf Central'''
** [http://www.netconfcentral.org/ http://www.netconfcentral.org/]
** Yuma Home Page
*** Free information on NETCONF and YANG, tutorials, on-line YANG module
validation and documentation database 
* '''Yuma123 open source project'''
** [http://sourceforge.net/projects/yuma123/
http://sourceforge.net/projects/yuma123/]
*** Download Yuma source and binaries; project forums and help
* '''Yang Central'''
** [http://www.yang-central.org/ http://www.yang-central.org]
** Free information and tutorials on YANG, free YANG tools for download
* '''NETCONF Working Group Wiki Page'''
** [http://trac.tools.ietf.org/wg/netconf/trac/wiki
http://trac.tools.ietf.org/wg/netconf/trac/wiki]
** 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'''
** [http://www.ibr.cs.tu-bs.de/projects/libsmi/
http://www.ibr.cs.tu-bs.de/projects/libsmi/]
** Free tools such as smidump, to convert SMIv2 to YANG
* '''YumaWorks'''
** [http://www.yumaworks.com/ http://www.yumaworks.com]
** Offers support, training, and consulting for Yuma.
** Offers YumaPro, a professional version of Yuma that includes
concurrency, external database support, sub-agent support, multiple
northbound interfaces, and more. API compatible with Yuma. Availability:
September, 2012. Licensed.
* '''Transpacket'''
** [http://www.transpacket.com/ http://www.transpacket.com]
** Offers Linux based embedded operating system distribution which uses
Yuma for configuration and monitoring.
** Offers support, training, and consulting for YANG and netconf.
=== Mailing Lists ===
* '''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'''
** [http://www.ietf.org/html.charters/netmod-charter.html
http://www.ietf.org/html.charters/netmod-charter.html]
** 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.

== Conventions Used in this Document ==
The following formatting conventions are used throughout this document:

<center>'''Documentation Conventions'''</center>



{| class=wikitable border="1"
! <center>Convention</center>
! <center>Description</center>

|-
|  '''--foo'''
|  CLI parameter foo

|-
|  '''<nowiki><foo></nowiki>'''
|  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 User Guide =
<center>'''netconfd Program Components'''</center>

[[Image:]]

== Introduction ==
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.


=== Features ===
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.
* <nowiki>Supports <candidate>, <running>, and <startup>
databases</nowiki>
* 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
* <nowiki>Automatic support for all capability registration and <hello>
message processing</nowiki>
* <nowiki>Full, automatic generation of all YANG module <capability>
contents, including features and deviations</nowiki>
* 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
* <nowiki>Complete <rpc-error> reporting support, including user-defined
errors via YANG error-app-tag and error-message statements.</nowiki>
* <nowiki>Several <rpc-error> extensions, including <bad-value> and
<error-number>, for easier debugging</nowiki>
* 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
i'''etf-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 <nowiki><get-schema> operation to retrieve YANG or YIN
modules from the server.</nowiki>
* <nowiki>Configurable default node handling, including full support of
the <with-defaults> standard, in </nowiki>'''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.
* <nowiki>Time filtering support for <get> and <get-config> requests
with 'modified-since' and 'if-modified-since' per-datastore
timestamps.</nowiki>

=== Setting the Server Profile ===
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'''<nowiki> setting will enable the <startup>
database if set to 'true'.</nowiki>
* '''--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.

=== Loading YANG Modules ===
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.

<nowiki>At run-time, the <load> operation (defined in
</nowiki>'''yuma-system.yang'''<nowiki>) 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.</nowiki>


=== Starting netconfd ===
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:<br/> 


         '''netconfd --version'''


* To get program help and exit:<br/> 


         '''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<br/> 


         '''netconfd --log-level=debug --log=~/mylog &'''


* To start the server interactively, and send all log messages to
STDOUT:<br/> 


         '''netconfd'''


* To start the server interactively, with a new log file:<br/> 


         '''netconfd –logfile=''mylogfile'''''


* To start the server interactively, and append to an existing log
file:<br/> 


         '''netconfd'' --''logfile''<nowiki>=mylogfile
–</nowiki>''log-append'''

* To get parameters from a configuration file:<br/> 


         '''netconfd –config<nowiki>=/etc/yuma/netconfd.conf</nowiki>'''

=== Stopping netconfd ===
To terminate the '''netconfd''' program when running interactively, use
the control-C character sequence. This will cause the server to cleanup
and terminate gracefully.

<nowiki>The <shutdown> or <restart> operations can also be used to
terminate or restart the server. </nowiki>The '''yuma-nacm.yang'''
access control rules must be configured to allow any user except the
'superuser' account to invoke this operation.

=== Signal Handling ===
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.


<center>'''Signals Recognized by netconfd'''</center>



{| class=wikitable border="1"
|  <center>'''signal'''</center>
|  <center>'''number'''</center>
|  <center>'''description'''</center>

|-
|  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.

=== Error Handling ===
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. <nowiki>The
server will attempt to find all the errors in the input <rpc> request,
and not stop detecting errors after one is found.</nowiki>
** 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.
** <nowiki>If the edit target is the <candidate> configuration, then
referential integrity tests are postponed until the <commit> operation
is attempted.</nowiki>
** 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.

=== Module Summary ===
The following YANG modules are built into the netconfd server, and
cannot be loaded manually with the '''module'''<nowiki> parameter or
<load> operation.</nowiki>


<center>'''Pre-loaded YANG Modules'''</center>



{| class=wikitable border="1"
|  <center>'''module'''</center>
|  <center>'''description'''</center>

|-
|  ietf-inet-types
|  standard data types

|-
|  ietf-netconf-monitoring
|  <nowiki>standard NETCONF monitoring, and the <get-schema>
operation</nowiki>

|-
|  ietf-netconf-partial-lock
|  <nowiki>standard NETCONF <partial-lock> and <partial-unlock>
operations</nowiki>

|-
|  ietf-netconf-with-defaults
|  <nowiki><with-defaults> extension</nowiki>

|-
|  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

|}
=== Notification Summary ===
The following notification event types are built into the '''netconfd'''
server:


<center>'''Pre-loaded Notifications'''</center>



{| class=wikitable border="1"
|  <center>'''module'''</center>
|  <center>'''event type'''</center>
|  <center>'''description'''</center>

|-
|  nc-notifications
|  <nowiki><replayComplete></nowiki>
|  Notification replay has ended

|-
|  nc-notifications
|  <nowiki><notificationComplete></nowiki>
|  Notification delivery has ended

|-
|  yuma-system
|  <nowiki><sysStartup></nowiki>
|  server startup event

|-
|  yuma-system
|  <nowiki><sysSessionStart></nowiki>
|  NETCONF session started

|-
|  yuma-system
|  <nowiki><sysSessionEnd></nowiki>
|  NETCONF session ended

|-
|  yuma-system
|  <nowiki><sysConfigChange></nowiki>
|  <nowiki><running> configuration has changed</nowiki>

|-
|  yuma-system
|  <nowiki><sysCapabilityChange></nowiki>
|  server capability added or deleted

|-
|  yuma-system
|  <nowiki><sysConfirmedCommit></nowiki>
|  confirmed-commit procedure event

|}
=== Operation Summary ===
The following protocol operations are built into the '''netconfd'''
server:


<center>'''Pre-loaded Operations'''</center>



{| class=wikitable border="1"
|  <center>'''module'''</center>
|  <center>'''operation'''</center>
|  <center>'''description'''</center>

|-
|  Ietf-netconf
|  <nowiki><cancel-commit></nowiki>
|  Cancel a confirmed-commit operation.

|-
|  ietf-netconf
|  <nowiki><close-session></nowiki>
|  Terminate the current session.

|-
|  ietf-netconf
|  <nowiki><commit></nowiki>
|  <nowiki>Activate edits in <candidate>.</nowiki>

|-
|  ietf-netconf
|  <nowiki><copy-config></nowiki>
|  Copy an entire configuration.

|-
|  notifications
|  <nowiki><create-subscription></nowiki>
|  Start receiving notifications.

|-
|  ietf-netconf
|  <nowiki><delete-config></nowiki>
|  Delete a configuration.

|-
|  ietf-netconf
|  <nowiki><discard-changes></nowiki>
|  <nowiki>Discard edits in <candidate>.</nowiki>

|-
|  ietf-netconf
|  <nowiki><edit-config></nowiki>
|  Edit the target configuration.

|-
|  ietf-netconf
|  <nowiki><get></nowiki>
|  <nowiki>Retrieve <running> or state data.</nowiki>

|-
|  ietf-netconf
|  <nowiki><get-config></nowiki>
|  Retrieve all or part of a configuration.

|-
|  yuma-mysession
|  <nowiki><get-my-session></nowiki>
|  Retrieve session customization parameters.

|-
|  ietf-netconf-monitoring
|  <nowiki><get-schema></nowiki>
|  Retrieve a YANG or YIN module definition file.

|-
|  ietf-netconf
|  <nowiki><kill-session></nowiki>
|  Terminate a NETCONF session.

|-
|  netconfd
|  <nowiki><load></nowiki>
|  Load a YANG module.

|-
|  ietf-netconf
|  <nowiki><lock></nowiki>
|  Lock a database.

|-
|  netconfd
|  <nowiki><no-op></nowiki>
|  No operation.

|-
|  ietf-netconf-partial-lock
|  <nowiki><partial-lock></nowiki>
|  <nowiki>Lock part of the <running> database</nowiki>

|-
|  ietf-netconf-partial-lock
|  <nowiki><partial-unlock></nowiki>
|  <nowiki>Unlock part of the <running> database</nowiki>

|-
|  netconfd
|  <nowiki><restart></nowiki>
|  Restart the server.

|-
|  yuma-mysession
|  <nowiki><set-my-session></nowiki>
|  Set the session customization parameters.

|-
|  yuma-system
|  <nowiki><set-log-level></nowiki>
|  Set the logging verbosity level.

|-
|  netconfd
|  <nowiki><shutdown></nowiki>
|  Shutdown the server.

|-
|  ietf-netconf
|  <nowiki><unlock></nowiki>
|  Unlock a database.

|-
|  ietf-netconf
|  <nowiki><validate></nowiki>
|  Validate a database

|}
=== Configuration Parameter List ===
The following configuration parameters are used by '''netconfd'''. Refer
to the CLI Reference for more details.


<center>'''netconfd CLI Parameters'''</center>



{| class=wikitable border="1"
|  <center>'''parameter'''</center>
|  <center>'''description'''</center>

|-
|  --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
|  <nowiki>Specifies the search path for the <startup> configuration
file.</nowiki>

|-
|  --default-style
|  <nowiki>Specifies the default <with-defaults> behavior</nowiki>

|-
|  --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
|  <nowiki>Set the number of seconds to wait for a <hello> PDU</nowiki>

|-
|  --idle-timeout
|  <nowiki>Set the number of seconds to wait for a <rpc> PDU</nowiki>

|-
|  --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
|  <nowiki>Specifies if the <candidate> or <running> configuration
should be the edit target</nowiki>

|-
|  --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
|  <nowiki>Enable or disable the <startup> database</nowiki>

|-
|  --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

|}
== Capabilities ==
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.

=== :base:1.0 ===
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.

=== :base:1.1 ===
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.

=== :candidate ===
The''' :candidate'''<nowiki> capability indicates that database edits
will be done to the <candidate> database, and saved with the <commit>
operation.</nowiki>

<nowiki>The <candidate> configuration is a shared scratch-pad, so it
should be used with the locking. </nowiki><nowiki>Database edits are
collected in the <candidate> and then applied, all or nothing, to the
<running> database, with the <commit> operation.</nowiki>

This capability is supported by default. It is controlled by the
--'''target''' configuration parameter (--target=candidate).

<nowiki>By default, only the superuser account can use the
<delete-config> operation on the <candidate> configuration.</nowiki>

=== :confirmed-commit ===
The ''':confirmed-commit '''<nowiki>capability indicates that the server
will support the <confirmed> and <confirm-timeout> parameters to the
<commit> operation. </nowiki><nowiki>If the 'base:1.1' protocol version
is in use, then the <persist> and <persist-id> parameters are also
supported.</nowiki>

<nowiki>The confirmed commit procedure requires that two <commit>
operations be used to apply changes from the candidate configuration to
the running configuration.</nowiki>

<nowiki>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.</nowiki>

<nowiki>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.</nowiki>

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, 

<nowiki>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.
</nowiki><nowiki>If the running and candidate configurations are
reverted, any intermediate edits made since the first <commit> operation
will be lost.</nowiki>

=== :interleave ===
The ''':interleave'''<nowiki> capability indicates that the server will
accept <rpc> requests other than <close-session> during notification
delivery. </nowiki>It is supported at all times, and cannot be
configured.

=== :netconf-monitoring ===
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'''<nowiki> subtree can be examined for all
the YANG modules that are available for download with the <get-schema>
operation.</nowiki>

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.

=== :notification ===
The ''':notification'''<nowiki> capability indicates that the server
will accept the <create-subscription> operation, and deliver
notifications to the session, according to the subscription
request.</nowiki>

<nowiki>All <create-subscription> options and features are
supported.</nowiki>

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'.

<nowiki>The first notification in the log will be for the <sysStartup>
event.</nowiki>

<nowiki>The <replayComplete> and <notificationComplete> event types are
not stored in the log.</nowiki>

=== :partial-lock ===
The ''':partial-lock'''<nowiki> capability indicates that RFC 5717 is
implemented, and partial locking of the <running> database is
supported.</nowiki>

<nowiki>The <copy-config> operation is not supported using the <running>
database as a target, so partial locks do not affect that
operation.</nowiki>

<nowiki>The <edit-config> operation on the <running> database is allowed
if the --target parameter is set to 'running'.</nowiki>

<nowiki>The <commit> operation will fail if any portion of the altered
configuration is locked by another session. </nowiki><nowiki>Data in the
<candidate> database which is identical to the corresponding data in the
<running> configuration is not affected by a <partial-lock>
operation.</nowiki>

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
* <nowiki>the number of <select> parameters in the <partial-lock>
request</nowiki>
* the number of nodes that can be locked by a single partial-lock

<nowiki>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. </nowiki><nowiki>The <lock-id>
'0' is not used.</nowiki>

=== :rollback-on-error ===
The ''':rollback-on-error'''<nowiki> 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.</nowiki>

<nowiki>The server will perform all PDU validation no matter what
<error-option> is selected.</nowiki>

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.

=== :schema-retrieval ===
The''' :schema-retrieval'''<nowiki> capability indicates that the
<get-schema> operation is supported.</nowiki>

The '''netconfd''' server supports this operation for all YANG modules
in use at the time.

<nowiki>The <identifier> parameter must be set to the name of the YANG
module.</nowiki>

<nowiki>The <format> parameter must be set to 'YANG'.</nowiki>

<nowiki>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.</nowiki>

=== :startup ===
The''' :startup'''<nowiki> capability indicates that the <startup>
configuration is supported by the server.</nowiki>

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:

* <nowiki>the server will allow the <startup> configuration to be the
source of a <get-config>.</nowiki>
* <nowiki>the server will allow the <startup> configuration to be the
target of a <copy-config> operation, if the source is the <running>
configuration.</nowiki>
* <nowiki>If the :validate capability is enabled, then the server will
allow the <startup> configuration to be the target of a <validate>
operation.</nowiki>
* <nowiki>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.</nowiki>

<nowiki>No other operations on the <startup> database are supported.
</nowiki><nowiki>The <startup> database cannot be edited with
<edit-config>, or over-written with <copy-config>.</nowiki>

=== :validate ===
The''' :validate'''<nowiki> capability indicates that the <validate>
operation is accepted, and the <test-option> for the <edit-config>
operation is also accepted, by the server.</nowiki>

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'''.

<nowiki>The <validate> operation can be invoked in several
ways:</nowiki>

* <nowiki>validate the <candidate> database if the
</nowiki>''':candidate''' capability is supported
* <nowiki>validate the <running> database</nowiki>
* <nowiki>validate the <startup> database if the </nowiki>''':startup'''
capability is supported
* <nowiki>validate an inline <config> element, which represents the
entire contents of a database.</nowiki>

<nowiki>The <test-option> parameter for the <edit-config> operation can
be used. </nowiki>This parameter has a significant impact on operations,
and needs to be used carefully.

* '''set'''<nowiki>: This option is not the default, but it is probably
the desired behavior for the <candidate> database. </nowiki>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. <nowiki>The <validate> operation
can be used before the <commit> is done, if desired.
</nowiki><nowiki>The same errors (if any) should be reported by
<validate> or <commit>.</nowiki>
* '''test-then-set'''<nowiki>: This option is the default, and will
cause a resource intensive validation procedure to be invoked every time
the <candidate> database is edited. </nowiki><nowiki>(The validation
procedure is always invoked on every edit to the <running>
configuration.) </nowiki>If any database validation errors are found (in
addition to the requested edit), then they will be reported. <nowiki>Use
the <error-path> field to determine which type of error is being
reported by the server.</nowiki>

=== :url ===
The ''':url'''<nowiki> capability indicates that the server accepts the
<url> parameter in NETCONF operations that use this parameter.
</nowiki>This capability can be disabled with the '''--with-url '''CLI
configuration parameter.

The following operations are affected by the :url capability:

* edit-config
** <nowiki><url> accepted instead of <config> as a configuration data
source</nowiki>
* copy-config
** <nowiki><url> accepted as a source parameter.</nowiki>
** <nowiki><url> accepted as a target paramter.</nowiki>
** <nowiki><url> to <url> copy not supported (optional to
implement)</nowiki>
* delete-config:
** <nowiki><url> accepted as source to delete</nowiki>
* validate
** <nowiki><url> accepted as a configuration source to
validate.</nowiki>

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. <nowiki>The NETCONF 'config' element is
used as the top-level element in all <url> files.</nowiki>

<nowiki>The $YUMA_DATAPATH environment variable or the $$datapth system
variable is used to find the file names specified in the <url> URI
string.</nowiki>

Example:

     <nowiki><url></nowiki>[../../../../../../../my-backup.xml
file:///my-backup.xml]<nowiki></url></nowiki>

=== :with-defaults ===
The''' :with-defaults'''<nowiki> capability indicates that the server
will accept the <with-defaults> parameter for the following
operations:</nowiki>

* <nowiki><get></nowiki>
* <nowiki><get-config></nowiki>
* <nowiki><copy-config></nowiki>

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. <nowiki>(Nodes
set in the <startup> are considered to be set by the client, not the
server.)</nowiki>

The '''--default-style'''<nowiki> configuration parameter is used to
control the behavior the server will use for these operations when the
<with-defaults> parameter is missing. </nowiki><nowiki>The server will
also use this default value when automatically saving the <running>
configuration to non-volatile storage.</nowiki>


=== :writable-running ===
The ''':writable-running'''<nowiki> capability indicates that the server
uses the <running> configuration as its edit target. </nowiki><nowiki>In
this case, the <target> parameter for the <edit-config> operation can
only be set to <running/>.</nowiki>

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.

<nowiki>Edits to the <running> configuration take affect right away, but
they are only saved to non-volatile storage automatically if the
</nowiki>'''with-startup''' configuration parameter is set to 'false'.

=== :xpath ===
<nowiki>The :xpath capability indicates that XPath filtering is
supported for the <get> and <get-config> operations.</nowiki>

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. <nowiki>It does not change the format of the <get> or
<get-config> output. </nowiki>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.
* <nowiki>All result nodes with common ancestor nodes will be grouped
together in the <rpc-reply>.</nowiki>
* All list nodes will include child nodes for any missing key leafs,
even if they were not requested in the 'select' expression.

== Databases ==
A NETCONF database is conceptually represented as an XML instance
document.

There are 3 conceptual databases, which all share the exact same
structure.

* <nowiki><candidate>: scratch-pad to gather edits to apply to <running>
all at once</nowiki>
* <nowiki><running>: configuration data in effect</nowiki>
* <nowiki><startup>: configuration data for the next reboot</nowiki>

<nowiki>When the <running> configuration is saved to non-volatile
storage, the top-level element of this document is the <config>
container element.</nowiki>

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.

<nowiki>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.</nowiki>

<nowiki>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.</nowiki>

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.

<nowiki>The server behavior for non-volatile storage of the <running>
configuration is set with the </nowiki>'''--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:


[[Image:]]

=== Database Locking ===
<nowiki>It is strongly suggested that the <lock> and <unlock> operations
be used whenever a database is being edited. </nowiki>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.

<nowiki>If the edit target is the <candidate> configuration, then the
<candidate> and <running> configurations should be locked.</nowiki>

<nowiki>If the edit target is the <running> configuration, then the
<running> and <startup> configurations should be locked.</nowiki>

<nowiki>Whenever the lock on the <candidate> configuration is released,
a <discard-changes> operation is performed by the server. </nowiki>This
is required by the NETCONF protocol.

<nowiki>Of the <candidate> configuration contains any edits, then a lock
will fail with a 'resource-denied' error. </nowiki><nowiki>In this case,
a lock on the <candidate> configuration cannot be granted until the
<discard-changes> operation is completed.</nowiki>

=== Using the <candidate> Database ===
<nowiki>The <candidate> database is available if the
</nowiki>''':candidate''' capability is advertised by the server.

<nowiki>The <lock> operation will fail on this database if there are any
edits already pending in the <candidate>. </nowiki><nowiki>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.</nowiki>

<nowiki>Once all the edits have been made, the <validate> operation can
be used to check if all database validation tests will pass.
</nowiki>This step is optional.

<nowiki>Once the edits are completed, the <commit> operation is used to
activate the configuration changes, and save them in non-volatile
storage.</nowiki>

<nowiki>The <discard-changes> operation is used to clear any edits from
this database.</nowiki>

=== Using the <running> Database ===
<nowiki>The <running> database is available at all times for
reading.</nowiki>

<nowiki>If the :writable-running capability is advertised by the server,
then this database will be available as the target for <edit-config>
operations.</nowiki>

<nowiki>Edits to the <running> configuration will take affect right
away, as each <edit-config> operation is completed.</nowiki>

<nowiki>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.</nowiki>

=== Using the <startup> Database ===
<nowiki>The <startup> database is available if the :startup capability
is advertised by the server.</nowiki>

<nowiki>The <copy-config> operation can be used to save the contents of
the <running> configuration to the <startup> configuration.</nowiki>

<nowiki>The <get-config> operation can be used to retrieve the contents
of the <startup> configuration.</nowiki>

<nowiki>The <delete-config> operation can be used to delete the
<startup> configuration. </nowiki>Only the superuser account is allowed
to do this, by default.

== 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''' 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''' 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";
         <nowiki>pattern '[a-z,A-Z][a-z,A-Z,0-9]{0,62}';</nowiki>
         }
     }


* A user name cane be 1 to 63 characters long.
* <nowiki>The first character must be a letter ['a' to 'z', or 'A' to
'Z']</nowiki>
* <nowiki>The remaining characters must be a letter ['a' to 'z', or 'A'
to 'Z'], or a number </nowiki><nowiki>['0' to '9'].</nowiki>

=== Session ID ===
<nowiki>The <session-id> assigned by the server is simply a
monotonically increasing number:</nowiki>


     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'''<nowiki> server will send a <hello> message if a valid
SSH2 session to the netconf subsystem is established.</nowiki>

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:


    
<nowiki><module-namespace>?module=<module-name>&revision=<module-date></nowiki>


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:


     '''<nowiki>&features=<feature-name>[,<feature-name>]*</nowiki>'''


If the module needs any external deviations applied, then the following
field will be added, and each deviation module name will be listed:


    
'''<nowiki>&deviations=<deviation-module-name>[,<deviation-module-name>]*</nowiki>'''


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.


<nowiki>Example server <hello> Message:</nowiki>


 <nowiki><nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
</nowiki>
    <nowiki><nc:capabilities> </nowiki>
      
<nowiki><nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
</nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:candidate:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:confirmed-commit:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:rollback-on-error:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:validate:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:xpath:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:notification:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:interleave:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:netconf:capability:with-defaults:1.0?basic=explicit&amp;supported=report-all:trim

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:netconf-monitoring:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
          urn:ietf:params:netconf:capability:schema-retrieval:1.0 
       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:xml:ns:yang:inet-types?module=ietf-inet-types&amp;revision=2009-05-13

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:xml:ns:netconf:monitoring?module=ietf-netconf-monitoring&amp;revision=2009-06-16

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:netconf:capability:with-defaults:1.0?module=ietf-with-defaults&amp;revision=2009-07-01&amp;features=with-defaults

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:xml:ns:yang:yang-types?module=ietf-yang-types&amp;revision=2009-05-13

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-interfaces?module=interfaces&amp;revision=2009-07-17

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-mysession?module=yuma-mysession&amp;revision=2009-08-11

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-nacm?module=yuma-nacm&amp;revision=2009-05-13

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&amp;revision=2008-07-14

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&amp;revision=2009-06-12

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&amp;revision=2009-04-10

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-types?module=yuma-types&amp;revision=2008-07-20

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/netconfd?module=netconfd&amp;revision=2009-05-28

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&amp;revision=2008-07-14

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-proc?module=yuma-proc&amp;revision=2009-07-17

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/yuma-system?module=yuma-system&amp;revision=2009-06-04

       <nowiki></nc:capability> </nowiki>
       <nowiki><nc:capability> </nowiki>
         
http://netconfcentral.org/ns/test?module=test&amp;revision=2009-06-10&amp;features=feature1,feature3,feature4

       <nowiki></nc:capability> </nowiki>
    <nowiki></nc:capabilities> </nowiki>
    <nowiki><nc:session-id>1</nc:session-id> </nowiki>
 <nowiki></nc:hello>]]>]]> </nowiki>

=== Client <hello> Message ===
The '''netconfd'''<nowiki> server requires a valid <hello> message from
the client before accepting any <rpc> requests.</nowiki>

Only the mandatory 'netconf base' URIs will be checked by the server.
<nowiki>All other <capability> elements will be ignored by the server.
</nowiki>

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.
<nowiki>Both the client and server send the 'base:1.x' (where 'x' is '1'
or '2') URIs they support (1 or 2 <capability> elements). </nowiki>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.

<nowiki>The following table shows the outcomes of all possible <hello>
processing scenarios:</nowiki>


{| class=wikitable border="1"
! <center>Client <hello></center>
! <center>Server <hello></center>
! <center>Outcome</center>

|-
|  <nowiki>[ none ]</nowiki>
|  <nowiki>[ any combination ]</nowiki>
|  Session dropped

|-
|  <nowiki>[ base:1.0 ]</nowiki>
|  <nowiki>[ base:1.0 ]</nowiki>
|  base:1.0 session started

|-
|  <nowiki>[ base:1.1 ]</nowiki>
|  <nowiki>[ base:1.0 ]</nowiki>
|  Session dropped

|-
|  <nowiki>[ base:1.0 base:1.1]</nowiki>
|  <nowiki>[ base:1.0 ]</nowiki>
|  base:1.0 session started

|-
|  <nowiki>[ base:1.0 ]</nowiki>
|  <nowiki>[ base:1.1 ]</nowiki>
|  Session dropped

|-
|  <nowiki>[ base:1.1 ]</nowiki>
|  <nowiki>[ base:1.1 ]</nowiki>
|  base:1.1 session started

|-
|  <nowiki>[ base:1.0 base:1.1]</nowiki>
|  <nowiki>[ base:1.1 ]</nowiki>
|  base:1.1 session started

|-
|  <nowiki>[ base:1.0 ]</nowiki>
|  <nowiki>[ base:1.0 base:1.1 ]</nowiki>
|  base:1.0 session started

|-
|  <nowiki>[ base:1.1 ]</nowiki>
|  <nowiki>[ base:1.0 base:1.1 ]</nowiki>
|  base:1.1 session started

|-
|  <nowiki>[ base:1.0 base:1.1]</nowiki>
|  <nowiki>[ base:1.0 base:1.1 ]</nowiki>
|  base:1.1 session started

|}
<nowiki>Example client <hello> Message:</nowiki>


 <nowiki><?xml version="1.0" encoding="UTF-8"?></nowiki>
 <nowiki><nc:hello
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"></nowiki>
    <nowiki><nc:capabilities></nowiki>
     
<nowiki><nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability></nowiki>
    <nowiki></nc:capabilities></nowiki>
 <nowiki></nc:hello></nowiki>

=== RPC Request Processing ===
<nowiki>The only PDU the netconfd server will accept during a NETCONF
session is the <rpc> message.</nowiki>

<nowiki>All aspects of NETCONF protocol conformance are supported for
contents of the <rpc> elements:</nowiki>

* <nowiki>All XML attributes in the <rpc> start tag will be returned to
the client (unchanged) in the <rpc-reply> element. </nowiki>The order of
the XML attributes may not be preserved.
* <nowiki>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. </nowiki><nowiki>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.</nowiki>
* <nowiki>The so-called mandatory 'message-id' attribute is ignored by
the server, along will all other XML attributes in the <rpc> element.
</nowiki>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.

<nowiki>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.</nowiki>

Access control will be enforced as follows:

* <nowiki>All <rpc> operation requests except <close-session> will be
checked in the access control model (yuma-nacm.yang). </nowiki>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.
* <nowiki>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.
</nowiki>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.

<nowiki>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. </nowiki>Instead,
unavailable nodes are just skipped.

<nowiki>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.</nowiki>


=== Session Termination ===
A session can terminate for several reasons:

* <nowiki><close-session> operation invoked</nowiki>
* <nowiki><kill-session> operation invoked</nowiki>
* 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)
* <nowiki>will discard all changes in the <candidate> configuration, if
this database was locked by the session.</nowiki>
* <nowiki>will remove the <session> list entry from the
</nowiki>'''/netconf-state/sessions''' container
* <nowiki>will generate a <sysSessionEnd> notification entry for the
closed or killed session</nowiki>

== Error Reporting ==
<nowiki>All errors are reported using the standard <rpc-error>
element.</nowiki>

<nowiki>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.</nowiki>

<nowiki>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.
</nowiki><nowiki>If there were errors in the input, then only 1 or more
<rpc-error> elements will be returned. </nowiki>It is possible that the
required data will be returned, after any errors, but not likely.

The internal '''netconfd'''<nowiki> error code for each <rpc-error> is
returned in an <error-info> extension called <error-number>.</nowiki>

<nowiki>Normally, the same <error-app-tag> and <error-message> values
are returned for a specific error number. </nowiki>However, some YANG
errors allow these fields to be user-defined. <nowiki>If there is a
user-defined <error-app-tag> and/or <error-message> values, then they
will be used instead of the default values.</nowiki>

This section describes the '''netconfd'''<nowiki> implementation details
which may affect <rpc-error> processing by a client
application.</nowiki>

=== <error-severity> Element ===
<nowiki>The <error-severity> field will always be set to 'error'.
</nowiki>There are no warnings generated by '''netconfd'''.

=== <error-tag> Element ===
<nowiki>All NETCONF <error-tag> enumerations are supported, except
'partial-operation'. </nowiki>This error is being deprecated in the
standard because nobody has implemented it.

<nowiki>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.</nowiki>

<nowiki>All standard <error-info> contents are supported.
</nowiki><nowiki>The following table summarizes the different
<error-tag> values. </nowiki><nowiki>The <error-number> parameter is not
shown in the 'error-info' column because it is added for every
error-tag.</nowiki>


<center>'''<nowiki><error-tag> Summary</nowiki>'''</center>



{| class=wikitable border="1"
|  <center>'''error-tag'''</center>
|  <center>'''error-info'''</center>
|  <center>'''description'''</center>

|-
|  access-denied
|  none
|  NACM denied access

|-
|  bad-attribute
| 
<nowiki><bad-attribute></nowiki><nowiki><bad-element></nowiki><nowiki><bad-value></nowiki>
|  just for the few attributes used in NETCONF

|-
|  bad-element
|  <nowiki><bad-element></nowiki><nowiki><bad-value></nowiki>
|  sometimes used instead of invalid-value

|-
|  data-exists
|  none
|  nc:operation='create'

|-
|  data-missing
|  none
|  nc:operation='delete' or'replace'

|-
|  in-use
|  none
|  edit on locked database

|-
|  invalid-value
|  <nowiki><bad-value></nowiki>
|  for typedef constraints

|-
|  lock-denied
|  <nowiki><session-id></nowiki>
|  <nowiki>for <lock> only</nowiki>

|-
|  missing-attribute
|  <nowiki><bad-attribute></nowiki>
|  just for the few attributes used in NETCONF

|-
|  missing-element
|  <nowiki><bad-element></nowiki>
|  mandatory parameters

|-
|  operation-not-supported
|  none
|  unsupported, false if-feature inside rpc

|-
|  operation-failed
|  none
|  when no other error-tag applies

|-
|  partial-operation
| 
<nowiki><ok-element></nowiki><nowiki><err-element></nowiki><nowiki><noop-element></nowiki>
|  not implemented

|-
|  resource-denied
|  none
|  malloc failed

|-
|  rollback-failed
|  none
|  rollback-on-error failed

|-
|  too-big
|  none
|  input too big to buffer

|-
|  unknown-attribute
|  <nowiki><bad-attribute></nowiki><nowiki><bad-element></nowiki>
|  for any non-NETCONF attributes found

|-
|  unknown-element
|  <nowiki><bad-element></nowiki>
|  wrong element name in a known namespace

|-
|  unknown-namespace
|  <nowiki><bad-element></nowiki>
|  module not loaded

|-
|  malformed-message
|  None
|  base:1.1 framing lost in transport layer

|}
=== <error-app-tag> Element ===
<nowiki>The <error-app-tag> field provided a more specific error
classification than the <error-tag> field. </nowiki><nowiki>It is
included in every <rpc-error> response.</nowiki>

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.

<nowiki>The following table describes the default <error-app-tag> values
used by </nowiki>'''netconfd''':


<center>'''<nowiki><error-app-tag> Summary</nowiki>'''</center>



{| class=wikitable border="1"
|  <center>'''error-app-tag'''</center>
|  <center>'''description'''</center>

|-
|  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)

|-
|  must-violation
|  must expression is false (YANG, sec. 13.4)

|-
|  no-access
|  access control violation

|-
|  no-matches
|  <nowiki><get-schema> module or revision search failed</nowiki>

|-
|  no-support
|  operation or sub-operation not implemented

|-
|  not-in-range
|  YANG range test failed

|-
|  not-in-value-set
|  YANG enumeration or bits name is invalid

|-
|  pattern-test-failed
|  YANG pattern test failed

|-
|  recover-failed
|  commit or rollback-on-error failed to leave the target database
unchanged

|-
|  resource-in-use
|  <nowiki>in-use error or <create-subscription> while a subscription is
already active</nowiki>

|-
|  ssh-error
|  SSH transport error

|-
|  too-few-elements
|  min-elements violation (YANG, sec. 13.3)

|-
|  too-many-elements
|  max-elements violation (YANG, sec. 13.2)

|}
=== <error-path> Element ===
<nowiki>The <error-path> field indicates the node that caused the
error.</nowiki>

It is encoded as a YANG instance-identifier.

<nowiki>If the node that caused the error is within the incoming <rpc>
request, then the error path will start with the <rpc> element, and
contain all the node identifiers from this document root to the node
that caused the error.</nowiki>


 <nowiki><error-path></nowiki>
     /nc:rpc/nc:edit-config/nc:config/nacm:nacm/nacm:groups/nacm:group
 <nowiki></error-path></nowiki>

<nowiki>The 'xmlns' attributes which define the 'nc' and 'nacm' prefixes
would be present in the <rpc-reply> or the <rpc-error> element start
tags.</nowiki>

If the node that caused the error is '''not'''<nowiki> within the
incoming <rpc> request, then the error path will start with the
top-level YANG module element that contains the error, not the <rpc>
element.</nowiki>


<nowiki>This extended usage of the <error-path> field is defined in the
YANG specification, not the NETCONF specification. </nowiki><nowiki>This
situation will occur if <validate> or <commit> operations detect errors.
</nowiki><nowiki>It can also occur if the <test-option> for the
<edit-config> operation is 'test-then-set', and errors unrelated to the
provided in-line <config> content are reported. and contain all the node
identifiers from this document root to the node that caused the
error.</nowiki>


 <nowiki><error-path></nowiki>
    
<nowiki>/nacm:nacm/nacm:groups/nacm:group[name='admin']/groupIdentity</nowiki>
 <nowiki></error-path></nowiki>

=== <error-message> Element ===
<nowiki>The <error-message> field provides a short English language
description of the error that usually corresponds to the <error-number>
field.</nowiki>

<nowiki>If the YANG <error-message> statement is available for the error
that occurred, it will be used instead of the default error
message.</nowiki>

=== <error-info> Element ===
<nowiki>The <error-info> container is used to add error-specific data to
the error report.</nowiki>

There are some standard elements that are returned for specific errors,
and some elements specific to the '''netconfd''' server.

<center>'''<nowiki><error-info> Summary</nowiki>'''</center>



{| class=wikitable border="1"
|  <center>'''child node'''</center>
|  <center>'''description'''</center>

|-
|  <nowiki><bad-attribute></nowiki>
|  name of the XML attribute that caused the error

|-
|  <nowiki><bad-element></nowiki>
|  name of the element that caused the error or contains the attribute
that caused the error

|-
|  <nowiki><bad-value></nowiki>
|  value that caused the error

|-
|  <nowiki><error-number></nowiki>
|  internal error number for the error condition

|-
|  <nowiki><missing-choice></nowiki>
|  name of the missing mandatory YANG choice

|-
|  <nowiki><session-id></nowiki>
|  session number of the current lock holder

|}
=== instance-required Error Example ===
The instance-required error-app-tag is generated when a YANG leaf is
mandatory, but was not set. <nowiki>An error will be returned right away
if the target is the <running> configuration, or if the (default)
</nowiki>'''test-then-set'''<nowiki> option is used for the
<test-option>. </nowiki><nowiki>Otherwise, this error is generated when
the <commit> operation is invoked.</nowiki>


<center>'''instance-required'''</center>



{| class=wikitable border="1"
|  <center>'''data'''</center>
|  <center>'''description'''</center>

|-
|  error-tag
|  data-missing

|-
|  error-app-tag
|  instance-required

|-
|  error-path
|  identifies the leaf that is missing

|-
|  error-info
|  none

|-
|  error-number
|  310

|}
Example Request:

* create /test2 <nowiki>(?s used to skip the mandatory <a2> leaf, but
the <foo> leaf is set)</nowiki><br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>none</nc:default-operation>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><t:test2 </nowiki> nc:operation="create" 
             xmlns:t="http://netconfcentral.org/ns/test"> 
             <nowiki><t:foo>xxx</t:foo> </nowiki>
          <nowiki></t:test2> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Error Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2" xmlns:t="http://netconfcentral.org/ns/test" 
    xmlns:ncx="http://netconfcentral.org/ncx"> 
    <nowiki><nc:rpc-error> </nowiki>
       <nowiki><nc:error-type>application</nc:error-type> </nowiki>
       <nowiki><nc:error-tag>data-missing</nc:error-tag> </nowiki>
       <nowiki><nc:error-severity>error</nc:error-severity> </nowiki>
       <nowiki><nc:error-app-tag>instance-required</nc:error-app-tag>
</nowiki>
       <nowiki><nc:error-path>/t:test2/t:a2</nc:error-path> </nowiki>
       <nowiki><nc:error-message xml:lang="en">required value instance
not found</nc:error-message> </nowiki>
       <nowiki><nc:error-info> </nowiki>
          <nowiki><ncx:error-number>310</ncx:error-number> </nowiki>
       <nowiki></nc:error-info> </nowiki>
    <nowiki></nc:rpc-error> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== missing-choice Error Example ===
The missing-choice error is generated when a YANG choice is mandatory,
but no case from the choice was set. <nowiki>An error will be returned
right away if the target is the <running> configuration, or if the
(default) </nowiki>'''test-then-set'''<nowiki> option is used for the
<test-option>. </nowiki><nowiki>Otherwise, this error is generated when
the <commit> operation is invoked.</nowiki>


<center>'''missing-choice error'''</center>



{| class=wikitable border="1"
|  <center>'''data'''</center>
|  <center>'''description'''</center>

|-
|  error-tag
|  data-missing

|-
|  error-app-tag
|  missing-choice

|-
|  error-path
|  identifies the parent of the missing choice 

|-
|  error-info
|  <nowiki><missing-choice></nowiki>

|-
|  error-number
|  296

|}
Example Request:

* create --target=/musttest (?s skip the mandatory choice)

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>none</nc:default-operation>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><t:musttest </nowiki> nc:operation="create" 
             xmlns:t="http://netconfcentral.org/ns/test"/> 
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc>]</nowiki>

Example Error Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2" xmlns:t="http://netconfcentral.org/ns/test" 
    xmlns:ncx="http://netconfcentral.org/ncx"> 
    <nowiki><nc:rpc-error xmlns:y="urn:ietf:params:xml:ns:yang:1">
</nowiki>
       <nowiki><nc:error-type>application</nc:error-type> </nowiki>
       <nowiki><nc:error-tag>data-missing</nc:error-tag> </nowiki>
       <nowiki><nc:error-severity>error</nc:error-severity> </nowiki>
       <nowiki><nc:error-app-tag>missing-choice</nc:error-app-tag>
</nowiki>
       <nowiki><nc:error-path>/t:musttest</nc:error-path> </nowiki>
       <nowiki><nc:error-message xml:lang="en">missing mandatory
choice</nc:error-message> </nowiki>
       <nowiki><nc:error-info> </nowiki>
          <nowiki><y:missing-choice
xmlns:y="urn:ietf:params:xml:ns:yang:1">musttest</y:missing-choice>
</nowiki>
          <nowiki><ncx:error-number>296</ncx:error-number> </nowiki>
       <nowiki></nc:error-info> </nowiki>
    <nowiki></nc:rpc-error> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>


=== no-matches Error Example ===
<nowiki>The no-matches error is generated when parameters for the
<get-schema> operation identify a non-existent YANG file.</nowiki>


<center>'''No Matches'''</center>



{| class=wikitable border="1"
|  <center>'''data'''</center>
|  <center>'''description'''</center>

|-
|  error-tag
|  operation-failed

|-
|  error-app-tag
|  no-matches

|-
|  error-path
|  <nowiki>identifies the <identifier> or <revision> parameter in the
<get-schema> request</nowiki>

|-
|  error-info
|  <nowiki><bad-value></nowiki>

|-
|  error-number
|  365

|}
Example Request:

* get-schema identifier=foo version= format=yang<br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><ns:get-schema
xmlns:ns="urn:ietf:params:xml:ns:netconf:state"> </nowiki>
       <nowiki><ns:identifier>foo</ns:identifier> </nowiki>
       <nowiki><ns:version/> </nowiki>
       <nowiki><ns:format>ns:yang</ns:format> </nowiki>
    <nowiki></ns:get-schema> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Error Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="3" xmlns:ns="urn:ietf:params:xml:ns:netconf:state" 
    xmlns:ncx="http://netconfcentral.org/ncx"> 
    <nowiki><nc:rpc-error> </nowiki>
       <nowiki><nc:error-type>protocol</nc:error-type> </nowiki>
       <nowiki><nc:error-tag>operation-failed</nc:error-tag> </nowiki>
       <nowiki><nc:error-severity>error</nc:error-severity> </nowiki>
       <nowiki><nc:error-app-tag>no-matches</nc:error-app-tag> </nowiki>
      
<nowiki><nc:error-path>/nc:rpc/ns:get-schema/ns:input/ns:identifier</nc:error-path>
</nowiki>
       <nowiki><nc:error-message xml:lang="en">no matches
found</nc:error-message> </nowiki>
       <nowiki><nc:error-info> </nowiki>
          <nowiki><ncx:bad-value>foo</ncx:bad-value> </nowiki>
          <nowiki><ncx:error-number>365</ncx:error-number> </nowiki>
       <nowiki></nc:error-info> </nowiki>
    <nowiki></nc:rpc-error> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>


=== not-in-range Error Example ===
The not-in-range error is generated when a numeric type viaolates a YANG
range statement.


<center>'''not-in-range'''</center>



{| class=wikitable border="1"
|  <center>'''data'''</center>
|  <center>'''description'''</center>

|-
|  error-tag
|  invalid-value

|-
|  error-app-tag
|  not-in-range

|-
|  error-path
|  identifies the leaf or leaf-list node that is not in range

|-
|  error-info
|  <nowiki><bad-value></nowiki>

|-
|  error-number
|  288

|}
Example Request:

* create /int8.1 value=1000

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="4"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>none</nc:default-operation>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><t:int8.1 </nowiki> nc:operation="create" 
            
<nowiki>xmlns:t="http://netconfcentral.org/ns/test">1000</t:int8.1>
</nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Error Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="4"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>none</nc:default-operation>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><t:int8.1 </nowiki> nc:operation="create" 
            
<nowiki>xmlns:t="http://netconfcentral.org/ns/test">1000</t:int8.1>
</nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>


== Protocol Operations ==
This section describes the '''netconfd''' implementation details that
may affect usage of the NETCONF protocol operations.

Every protocol operation is defined with a YANG rpc statement.

All NETCONF operations and several proprietary operations are supported,

=== <cancel-commit> ===
<nowiki>The <cancel-commit> operation is used to cancel a confirmed
commit procedure in progress.</nowiki>

<nowiki>A <sysSessionEnd> notification with a <terminationReason> field
set to 'closed' will be generated when this operation is
invoked.</nowiki>


<center>'''<nowiki><cancel-commit> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  ietf-netconf.yang

|-
|  Capabilities needed:
|  base:1.1

|}
Mandatory Parameters:

* none

Optional Parameters:

* persist:<nowiki>If the 'persist' string was provided in the <commit>
operation, then this parameter must be present, and the value must
match. </nowiki>Only the session that started the confirmed commit can
use this operation without providing a 'persist' parameter.

Returns:

* <nowiki><ok/>; an <rpc-reply> will be sent to the session before
terminating the session.</nowiki>

Possible Operation Errors:

* none

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><nc:cancel-commit></nowiki>
      <nowiki><nc:persist>mycommit</nc:persist></nowiki>
    <nowiki></nc:cancel-commit></nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <close-session> ===
<nowiki>The <close-session> operation is always allowed, even if access
control rules exist which somehow disallow 'exec' privileges to a
session for this operation.</nowiki>

<nowiki>A <sysSessionEnd> notification with a <terminationReason> field
set to 'closed' will be generated when this operation is
invoked.</nowiki>


<center>'''<nowiki><close-session> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* <nowiki><ok/>; an <rpc-reply> will be sent to the session before
terminating the session.</nowiki>

Possible Operation Errors:

* none

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><nc:close-session/> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <commit> ===
<nowiki>The <commit> operation is only available when the
</nowiki>''':candidate''' capability is supported.

The parameters are only supported if the ''':confirmed-commit'''
capability is supported.

<nowiki>This operation causes all the edits in the <candidate>
configuration to be applied to the <running> configuration. </nowiki>If
there are no edits, then this operation has no affect.

<nowiki>If multiple sessions have made edits to the <candidate>
configuration (because locking was not used), then all these edits will
be applied at once, not just the edits from the current
session.</nowiki>

<nowiki>It the <candidate> or <running> configurations are locked by
another session, then this operation will fail with an 'in-use'
error.</nowiki>

<nowiki>Normally, if there have been no changes made to the <candidate>
configuration, then this operation has no effect. </nowiki><nowiki>An
<ok/> response will be returned without altering the <running>
configuration.</nowiki>

<nowiki>However, if the <running> configuration encountered any errors
during the initial load from NV-storage </nowiki><nowiki>(such as
startup-cfg.xml), then the current contents of the <running>
configuration will be written to NV-storage, even if there are no
changes to the <candidate> configuration.</nowiki>

The :confirmed-commit capability is fully supported:

* confirmed-commit:1.0
* confirmed-commit:1.1

<center>'''<nowiki><commit> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  4

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :candidate:confirmed-commit

|}
Mandatory Parameters:

* none

Optional Parameters:

* '''confirmed''':
** type: empty
** default: none
** capabilities needed: confirmed-commit
** This parameter indicates that a confirmed commit operation should be
started or extended.
* '''confirm-timeout:'''
** type: number
** default: 600
** capabilities needed: confirmed-commit
** This parameter indicates the number of seconds to wait before
canceling the confirmed commit automatically.
* '''persist''':
** type: string
** default: none
** capabilities needed: confirmed-commit and base:1.1
** This parameter sets the string that all sessions can use to access
this confirmed commit procedure.
* '''persist-id:'''
** type: string
** default: none
** capabilities needed: confirmed-commit and base:1.1
** This parameter changes the 'persist' string that all sessions can use
to access this confirmed commit procedure. It is used to allow access to
the confirmed commit operation, if the 'persist' parameter is not
present.

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied: access control configured to deny access to this
operation

* in-use<nowiki>: the <candidate> or <running> configuration is locked
by another session.</nowiki>
* operation-failed
** must-violation: must statement is false
** too-few-elements: min-elements expression is false
** too-many-elements: max-elements expression is false
** data-not-unique: unique statement violation
* data-missing: mandatory statement violation or missing leafref path
object

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="5"> 
    <nowiki><nc:commit/> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="5"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <copy-config> ===
<nowiki>The <copy-config> operation is used to transfer entire
configuration databases in one operation.</nowiki>

This is a destructive 'stop-on-error' operation. <nowiki>It is not like
<edit-config> or <commit>, which can be used in an 'all-or-nothing'
manner.</nowiki>

<nowiki>A failed <copy-config> can leave the target of the operation in
an unstable, invalid state. </nowiki>This operation should be used with
caution.

<nowiki>The <source> and <target> parameters are simple to understand,
but there are many interactions and some complexity, due to so many
combinations of optional capabilities that are possible.</nowiki>

<nowiki>When in-line configuration data is used in the <source>
parameter, it is applied to the <target> </nowiki>differently, depending
on the database.

* <nowiki>If the <target> is the <startup> configuration, then the new
configuration simply overwrites the old one, and no validation is done
at all.</nowiki>
* <nowiki>If the <target> is the <candidate> or <running> configuration,
then the new configuration is applied as if the operation was an
<edit-config> operation with a <default-operation> parameter set to
'replace'. </nowiki>All validation and access control procedures are
followed.

<nowiki>The <with-defaults> parameter is also available for filtering
the output as it is copied to the target.</nowiki>

<center>'''<nowiki><copy-config> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  2

|-
|  Max parameters:
|  3

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|-
|  Capabilities optional:
|  :candidate:writable-running:startup

|}
Mandatory Parameters:

* '''source'''
** type: container with 1 of N choice of leafs
** usage: mandatory
** default: none
** This parameter specifies the name of the source database for the copy
operation.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: none
*** '''startup'''
**** type: empty
**** capabilities needed: startup
*** '''config:'''
**** type: container (in-line configuration data)
**** capabilities needed: none
***** The '''netconfd''' server will only the superuser account is
allowed to copy in-line data into a database. All other users will get
an 'access'-denied' error. Access to the entire database is required for
this operational mode.
* '''target'''
** type: container with 1 of N choice of leafs
** usage: mandatory
** default: none
** This parameter specifies the name of the target database for the copy
operation.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''startup'''
**** type: empty
**** capabilities needed: startup

Optional Parameters:

* '''with-defaults'''
** type: enumeration (none report-all report-all-tagged trim explicit)
** default: none
** capabilities needed: with-defaults
** This parameter controls how nodes containing only default values are
copied to the target database. <nowiki>If the <target> parameter is
<candidate>, then this parameter will be ignored.</nowiki>

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied''': '''access control configured to deny access to this
operation

* in-use<nowiki>: the configuration indicated by the <target> parameter
is locked by another session.</nowiki>
* <nowiki><commit> errors, if the </nowiki>'''target'''<nowiki>
parameter is the <running> configuration</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="7"> 
    <nowiki><nc:copy-config> </nowiki>
       <nowiki><nc:source> </nowiki>
          <nowiki><nc:running/> </nowiki>
       <nowiki></nc:source> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:startup/> </nowiki>
       <nowiki></nc:target> </nowiki>
    <nowiki></nc:copy-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="7"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <create-subscription> ===
<nowiki>The <create-subscription> operation is used to start a NETCONF
notifications subscription.</nowiki>

Only the 'NETCONF' stream is supported by '''netconfd'''.

<nowiki>A replay subscription is created by including the <startTime>
parameter.</nowiki>

<nowiki>The subscription will continue until the session is closed,
unless the <stopTime> parameter is present. </nowiki><nowiki>In that
case, the subscription will terminate at that tim (if in the future) or
when all replay notifications with a lower <eventTime> value have been
delivered.</nowiki>

The :notification and :interleave capabilities are always supported by
netconfd.

The replay notification feature can be controlled with the
--eventlog-size configuration parameter. If this is set to '0', then no
stored notifications will be available for replay. The default is store
the most recent 1000 system notification events.

An entry will be created in the 'subscriptions' data structure in the
ietf-netconf-monitoring module, when the subscription is successfully
started.


<center>'''<nowiki><create-subscription> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  4

|-
|  Return type:
|  status

|-
|  YANG file:
|  notifications.yang

|-
|  Capabilities needed:
|  :notification

|-
|  Capabilities optional:
|  :interleave

|}
Mandatory Parameters:

* none

Optional Parameters:

* '''stream'''
** type: string
** default: 'NETCONF'
** This parameter specifies the name of the notification stream for this
subscription request. Only the 'NETCONF' stream is supported.
* '''filter'''
** <nowiki>type: anyxml (same as the <get> or <get-config> filter
parameter)</nowiki>
** default: none
** This parameter specifies a boolean filter that should be applied to
the stream. <nowiki>This is the same format as the standard <filter>
element in RFC 4741, except that instead of creating a subset of the
database for an <rpc-reply> PDU, the filter is used as a boolean test to
send or drop each notification delivered from the server.</nowiki>
*** If any nodes are left in the 'test response', the server will send
the entire notification.
*** If the result is empty after the filter is applied to the “test
response”, then the server will not send the notification at all.
*** It is possible that access control will either cause the a
notification to be dropped entirely, or may be pruned and still
delivered. The standard is not clear on this topic. The
'''netconfd'''<nowiki> server will prune any unauthorized payload from
an eventType, but if the <eventType> itself is unauthorized, the entire
notification will be dropped.</nowiki>
* '''startTime'''
** type: yang:date-and-time
** This parameter causes any matching replay notifications to be
delivered by the server, if notification replay is supported by the
server. <nowiki>A notification will match if its <eventTime> value is
greater or equal to the value of this parameter.</nowiki>
* '''stopTime'''
** type: yang:date-and-time
** usage: not allowed unless startTime is also present
** This parameter causes any matching replay notifications to be
delivered by the server, if notification replay is supported by the
server. <nowiki>A notification will match if its <eventTime> value is
less than the value of this parameter. </nowiki>
*** This parameter must be greater than the '''startTime''' parameter,
or an error will be returned by the server.

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied
* subscription already active

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><ncEvent:create-subscription</nowiki>
       xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0"> 
      
<nowiki><ncEvent:startTime>2009-01-01T00:00:00Z</ncEvent:startTime>
</nowiki>
    <nowiki></ncEvent:create-subscription> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <delete-config> ===
<nowiki>The <delete-config> operation is used to delete the entire
contents of a NETCONF database.</nowiki>

By default, only the superuser account is allowed to invoke this
operation.

If the ''':startup'''<nowiki> capability is supported, then the
<startup> configuration can be cleared. </nowiki>This will affect the
startup file that was actually loaded into the server, or the default
file if the '''--no-startup''' configuration parameter was used.

<nowiki>The <running> and <candidate> configurations cannot be
deleted.</nowiki>

<nowiki>The <startup> configuration can be repopulated with the
<copy-config> or <commit> operations.</nowiki>


<center>'''<nowiki><delete-config> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :startup

|}
Mandatory Parameters:

* '''target'''
** type: container with 1 of N choice of leafs
** <nowiki>This parameter specifies the name of the target database for
the <delete-config> operation.</nowiki>
** container contents: 1 empty leaf value supported:
*** '''startup'''

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied
* <nowiki>in-use: <startup> database is locked</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><nc:delete-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:startup/> </nowiki>
       <nowiki></nc:target> </nowiki>
    <nowiki></nc:delete-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <discard-changes> ===
<nowiki>The <discard-changes> operation is used to remove any edits from
the <candidate> configuration. </nowiki><nowiki>This is done by deleting
the contents of the <candidate> and re-filling it with the contents of
the <running> configuration.</nowiki>

<nowiki>If the <candidate> configuration is locked by another session,
this operation will fail.</nowiki>


<center>'''<nowiki><discard-changes> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :candidate

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><nc:discard-changes/> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:


 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="3"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <edit-config> ===
<nowiki>The <edit-config> operation is used to alter the target
database.</nowiki>

<nowiki>The target database is the <candidate> configuration if the
</nowiki>'''--target'''<nowiki> configuration parameter is set to
'candidate', and the <running> configuration if it is set to
'running'.</nowiki>

The''' nc:operation'''<nowiki> attribute must appear within the inline
<config> parameter contents if the <default-operation> parameter is set
to 'none', or the <edit-config> operation will have no affect.
</nowiki>This is not an error condition.

If the''' nc:operation'''<nowiki> attribute is used, then it may appear
any number of times, and be arbitrarily nested within the <config>
parameter contents. </nowiki>Certain combinations will cause errors,
however, so this must be done carefully. For example, a 'delete'
operation nested within a 'create' operation is an error, because the
conditions for both operations cannot possibly be satisfied at once.
Other combinations, such as 'merge' within 'create' are not an error
because there are no conflicting conditions present for either
operation.


<center>'''<nowiki><edit-config> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  2

|-
|  Max parameters:
|  5

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :candidate or :writable-running

|-
|  Capabilities optional:
|  :rollback-on-error:validate

|}
Mandatory Parameters:

* '''config'''
** type: anyxml
** This parameter specifies the subset of the database that should be
changed.
* '''target'''
** type: container with 1 of N choice of leafs
** This parameter specifies the name of the target database for the edit
operation.
** container contents: choice: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: :writable-running

Optional Parameters:

* '''default-operation'''
** type: enumeration (merge replace none)
** default: merge
** This parameter specifies which edit operation will be in effect at
the start of the operation, before any '''nc:operation '''attribute is
found.
* '''error-option'''
** type: enumeration (stop-on-error continue-on-error rollback-on-error
** default: stop-on-error
** This parameter specifies what the server should do when an error is
encountered.
* 
* '''test-option'''
** type: enumeration (test-then-set set test-only)
** default: 'test-then-set' if ''':validate '''capability is supported
and 'set' otherwise

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied
* in-use (target database is locked by another session)
* <nowiki><commit> validation errors: if
</nowiki>'''test-then-set'''<nowiki> is used or the target is the
<running> configuration.</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="12"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>merge</nc:default-operation>
</nowiki>
       <nowiki><nc:test-option>set</nc:test-option> </nowiki>
       <nowiki><nc:error-option>rollback-on-error</nc:error-option>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><t:musttest
xmlns:t="http://netconfcentral.org/ns/test"> </nowiki>
             <nowiki><t:A </nowiki>
<nowiki>nc:operation="create">'testing one two'</t:A> </nowiki>
          <nowiki></t:musttest> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="12"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <get> ===
<nowiki>The <get> operation is used to retrieve data from the <running>
configuration, or non-configuration data available on the
server.</nowiki>

<nowiki>The simple command (<get/>) will cause all available data to be
retrieved from the server. </nowiki>This may be generate a large
response and waste resources.

<nowiki>To select only specific subsets of all available data, use
subtree or XPath filtering by providing a <filter> parameter.
</nowiki>Namespace prefixes are optional to use in XPath expressions.
The netconfd will figure out the proper namespace, if possible. If
prefixes are used, then they must be valid XML prefixes with a namespace
properly declared in the PDU.

<nowiki>The retrieval of leaf or leaf-list nodes with default values is
controlled with the <with-defaults> parameter.</nowiki>

<nowiki>If a portion of the requested data is not available due to
access control restrictions, then that data is silently dropped from the
<rpc-reply> message. </nowiki>It is implicitly understood that the
client is only requesting data for which it is authorized to receive, in
the event such data is selected in the request.


<center>'''<nowiki><get> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  3

|-
|  Return type:
|  data

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|-
|  Capabilities optional:
|  :candidate:startup

:with-defaults

|}
Mandatory Parameters:

* none

Optional Parameters:

* '''filter '''
** '''type='subtree''''
*** type: anyxml
*** This parameter specifies the subset of the database that should be
retrieved.
** '''type='xpath' select='expr''''
*** type: empty
*** The unqualified '''select''' attribute is used to specify an XPath
filter.
* '''with-defaults'''
** type: enumeration (none report-all report-all-tagged trim explicit)
** usage: [#9.10. --default-style|outline --default-style]
'''configuration parameter used as the default if no value is provided
** This parameter controls how default leaf and leaf-list nodes are
returned by the server.
* '''if-modified-since'''
** type: date-and-time
** usage: optional
** This parameter requests that configuration data only be returned if
any of the running datastore contents have been modified since this
value. Monitoring data (config = false) does not affect the datastore
timestamp. <nowiki>If the running datastore has not been modified since
this timestamp, then an empty <data> element will be returned, and the
request will not be processed.</nowiki>

Returns:

* <nowiki><data> element</nowiki>

Possible Operation Errors:

* access-denied
* invalid-value

Example subtree Filter Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="4"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="subtree"> </nowiki>
          <nowiki><proc:proc
xmlns:proc="http://netconfcentral.org/ns/proc"> </nowiki>
             <nowiki><proc:cpuinfo> </nowiki>
                <nowiki><proc:cpu> </nowiki>
                   <nowiki><proc:cpu_MHz/> </nowiki>
                <nowiki></proc:cpu> </nowiki>
             <nowiki></proc:cpuinfo> </nowiki>
          <nowiki></proc:proc> </nowiki>
       <nowiki></nc:filter> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Equivalent XPath Filter Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="4"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="xpath"
select="/proc/cpuinfo/cpu/cpu_MHz"/> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc>]</nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    last-modified="2011-08-21T17:51:46Z"
    message-id="4"> 
    <nowiki><nc:data> </nowiki>
       <nowiki><proc:proc
xmlns:proc="http://netconfcentral.org/ns/proc"> </nowiki>
          <nowiki><proc:cpuinfo> </nowiki>
             <nowiki><proc:cpu> </nowiki>
                <nowiki><proc:cpu_MHz>1600.000</proc:cpu_MHz> </nowiki>
                <nowiki><proc:processor>0</proc:processor> </nowiki>
             <nowiki></proc:cpu> </nowiki>
             <nowiki><proc:cpu> </nowiki>
                <nowiki><proc:cpu_MHz>2667.000</proc:cpu_MHz> </nowiki>
                <nowiki><proc:processor>1</proc:processor> </nowiki>
             <nowiki></proc:cpu> </nowiki>
          <nowiki></proc:cpuinfo> </nowiki>
       <nowiki></proc:proc> </nowiki>
    <nowiki></nc:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <get-config> ===
<nowiki>The <get-config> operation is used to retrieve data from a
NETCONF configuration database.</nowiki>

<nowiki>To select only specific subsets of all available data, use
subtree or XPath filtering by providing a <filter> parameter.
</nowiki>Namespace prefixes are optional to use in XPath expressions.
The netconfd will figure out the proper namespace, if possible. If
prefixes are used, then they must be valid XML prefixes with a namespace
properly declared in the PDU.

<nowiki>The retrieval of leaf or leaf-list nodes with default values is
controlled with the <with-defaults> parameter.</nowiki>

<nowiki>If a portion of the requested data is not available due to
access control restrictions, then that data is silently dropped from the
<rpc-reply> message. </nowiki>It is implicitly understood that the
client is only requesting data for which it is authorized to receive, in
the event such data is selected in the request.

<center>'''<nowiki><get-config> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  4

|-
|  Return type:
|  data

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|-
|  Capabilities optional:
|  :candidate:startup

:with-defaults

|}
Mandatory Parameters:

* '''source'''
** type: container with 1 of N choice of leafs
** usage: mandatory
** This parameter specifies the name of the source database for the
retrieval operation.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: none
*** '''startup'''
**** type: empty
**** capabilities needed: startup

Optional Parameters:

* '''filter '''
** '''type='subtree''''
*** type: anyxml
*** This parameter specifies the subset of the database that should be
retrieved.
** '''type='xpath' select='expr''''
*** type: empty
*** The unqualified '''select''' attribute is used to specify an XPath
filter.
* '''with-defaults'''
** type: enumeration (none report-all report-all-tagged trim explicit)
** usage: '''--default-style '''configuration parameter used as the
default if no value is provided
** This parameter controls how default leaf and leaf-list nodes are
returned by the server.
* '''if-modified-since'''
** type: date-and-time
** usage: optional
** This parameter requests that configuration data only be returned if
any of the specified datastore contents have been modified since this
value. <nowiki>If the specified datastore has not been modified since
this timestamp, then an empty <data> element will be returned, and the
request will not be processed.</nowiki>

Returns:

* <nowiki><data> element</nowiki>

Possible Operation Errors:

* access-denied
* invalid-value

Example subtree Filter Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><nc:get-config> </nowiki>
       <nowiki><nc:source> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:source> </nowiki>
       <nowiki><nc:filter type="subtree"> </nowiki>
          <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/nacm"> </nowiki>
             <nowiki><nacm:rules> </nowiki>
                <nowiki><nacm:moduleRule/> </nowiki>
             <nowiki></nacm:rules> </nowiki>
          <nowiki></nacm:nacm> </nowiki>
       <nowiki></nc:filter> </nowiki>
    <nowiki></nc:get-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Equivalent XPath Filter Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><nc:get-config> </nowiki>
       <nowiki><nc:source> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:source> </nowiki>
       <nowiki><nc:filter type="xpath" select="/nacm/rules/moduleRule"/>
</nowiki>
    <nowiki></nc:get-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    last-modified="2011-08-21T17:51:46Z"
    message-id="3"> 
    <nowiki><nc:data> </nowiki>
       <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/nacm"> </nowiki>
          <nowiki><nacm:rules> </nowiki>
             <nowiki><nacm:moduleRule> </nowiki>
                <nowiki><nacm:moduleName>netconf</nacm:moduleName>
</nowiki>
                <nowiki><nacm:allowed-rights>read
exec</nacm:allowed-rights> </nowiki>
               
<nowiki><nacm:allowed-group>nacm:guest</nacm:allowed-group> </nowiki>
             <nowiki></nacm:moduleRule> </nowiki>
             <nowiki><nacm:moduleRule> </nowiki>
                <nowiki><nacm:moduleName>netconfd</nacm:moduleName>
</nowiki>
                <nowiki><nacm:allowed-rights>read write
exec</nacm:allowed-rights> </nowiki>
               
<nowiki><nacm:allowed-group>nacm:admin</nacm:allowed-group> </nowiki>
                <nowiki><nacm:comment>access to shutdown and restart
rpcs</nacm:comment> </nowiki>
             <nowiki></nacm:moduleRule> </nowiki>
             <nowiki><nacm:moduleRule> </nowiki>
                <nowiki><nacm:moduleName>netconf</nacm:moduleName>
</nowiki>
                <nowiki><nacm:allowed-rights>read write
exec</nacm:allowed-rights> </nowiki>
               
<nowiki><nacm:allowed-group>nacm:admin</nacm:allowed-group> </nowiki>
               
<nowiki><nacm:allowed-group>nacm:monitor</nacm:allowed-group> </nowiki>
             <nowiki></nacm:moduleRule> </nowiki>
          <nowiki></nacm:rules> </nowiki>
       <nowiki></nacm:nacm> </nowiki>
    <nowiki></nc:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>


=== <get-my-session> ===
<nowiki>The <get-my-session> operation is used to retrieve session
customization data for the current session.</nowiki>

The session indent amount, line size, and default behavior for the
with-defaults parameter can be controlled at this time.

<center>'''<nowiki><get-my-session> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  data

|-
|  YANG file:
|  yuma-mysession.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* '''<nowiki><indent></nowiki>'''
** type: uint32 (range 0 .. 9)
** This parameter specifies the desired indent amount for the session.
* '''<nowiki><linesize></nowiki>'''
** type: uint32 (range 40 .. 1024)
** This parameter specifies the desired line length for the session.
* '''<nowiki><with-defaults></nowiki>'''
** type: enumeration (report-all report-all-tagged trim explicit)
** This parameter specifies the desired default with-defaults behavior
for the session. The server-wide default value is set with the
'''--default-style '''configuration parameter.

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="2"> 
    <nowiki><myses:get-my-session
xmlns:myses="http://netconfcentral.org/ns/mysession"/> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="2"> 
    <nowiki><myses:indent
xmlns:myses="http://netconfcentral.org/ns/mysession"></nowiki>
       3
    <nowiki></myses:indent> </nowiki>
    <nowiki><myses:linesize
xmlns:myses="http://netconfcentral.org/ns/mysession"></nowiki>
       72
    <nowiki></myses:linesize> </nowiki>
    <nowiki><myses:with-defaults
xmlns:myses="http://netconfcentral.org/ns/mysession"></nowiki>
       report-all
    <nowiki></myses:with-defaults> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <get-schema> ===
<nowiki>The <get-schema> operation is used to retrieve YANG modules and
submodules from the server.</nowiki>

The 'YANG' and 'YIN' formats are supported for all YANG files loaded
into the server.

<nowiki>If the <version> parameter is set to the empty string, then the
server will return whichever version it supports. </nowiki>If multiple
versions are supported, then the server will pick a canonical version,
which may not be the most recent version.

<nowiki>The <identifier> parameter must contain the name of the YANG
file without any path or file extension specification.</nowiki>

<center>'''<nowiki><get-schema> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  3

|-
|  Max parameters:
|  3

|-
|  Return type:
|  data

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :schema-retrieval

|}
Mandatory Parameters:

* '''identifier'''
** type: string
** This parameter specifies the name of the module to retrieve.
*** Do not use any path specification of file extension; just the module
name is entered.
*** The name is case-sensitive, and must be specified exactly as
defined.
* '''version'''
** type: string
** This parameter specifies the version of the module to retrieve.
*** This will be the most recent YANG revision date string defined in a
module revision statement.
*** If any version is acceptable, or if the specific version is not
known, then use the empty string.
* '''format'''
** type: enumeration (XSD YANG YIN RNG)
** This parameter specifies the format of the module to be retrieved.
Only the YANG format is supported.
*** YANG: RFC 6020
*** YIN: RFC 6020

Returns:

* <nowiki><data> element (contents of the YANG file)</nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="55"> 
    <nowiki><ns:get-schema
xmlns:ns="urn:ietf:params:xml:ns:netconf:state"> </nowiki>
       <nowiki><ns:identifier>ietf-with-defaults</ns:identifier>
</nowiki>
       <nowiki><ns:format>YANG</ns:format> </nowiki>
       <nowiki><ns:version/> </nowiki>
    <nowiki></ns:get-schema> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="55"> 
    <nowiki><ns:data xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
</nowiki>
 <nowiki>*** entire contents of YANG module would be here, no extra
indenting ***</nowiki>
    <nowiki></ns:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <kill-session> ===
<nowiki>The <kill-session> operation is used to force the termination of
another NETCONF session. </nowiki>This is sometimes needed if an idle
session which is holding one or more locks was abandoned. It may also be
needed for security reasons. In any case, this operation should be used
with extreme caution.


<center>'''<nowiki><kill-session> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* '''session-id'''
** type: uint32 (range: 1.. max)
** default: none
** This parameter specifies the session number of the currently active
NETCONF session that should be terminated.

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="42"> 
    <nowiki><nc:kill-session> </nowiki>
       <nowiki><nc:session-id>1</nc:session-id> </nowiki>
    <nowiki></nc:kill-session> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="42"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <load> ===
<nowiki>The <load> operation is used to load new YANG modules at
run-time.</nowiki>

The module file must already be present in the module search path of the
server.

There must not be any version of the module already loaded.

This operation is tagged as '''nacm:secure''', so by default, only the
super user account is allowed to use it.


<center>'''<nowiki><load> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  3

|-
|  Return type:
|  data

|-
|  YANG file:
|  yuma-system.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* '''module'''
** The name of the YANG module to load

Optional Parameters:

* '''revision'''
** The revision date of the module to load. If missing, then server can
select the version to use.
* '''deviation'''
** The name of a deviation module to load before loading this module.
Zero or more instances of this parameter can be entered. Duplicates will
be ignored.

Returns:

* <nowiki><mod-revision></nowiki>
** The revision date of the module that was already loaded, or was just
loaded.

Possible Operation Errors:

* access-denied
* module not found
* version not found
* different version already loaded
* module parsing errors
* resource errors

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="52"> 
    <nowiki><nd:load xmlns:nd="http://netconfcentral.org/ns/netconfd">
</nowiki>
       <nowiki><nd:module>test2</nd:module> </nowiki>
    <nowiki></nd:load> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="52"> 
    <nowiki><nd:mod-revision
xmlns:nd="http://netconfcentral.org/ns/netconfd"></nowiki>
        2008-10-15
    <nowiki></nd:mod-revision> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <lock> ===
<nowiki>The <lock> operation is used to insure exclusive write access to
an entire configuration database.</nowiki>

<nowiki>The <running> configuration can be locked at any time, if it is
currently unlocked.</nowiki>

If the ''':startup'''<nowiki> capability is supported, the <startup>
configuration can be locked at any time, if it is currently
unlocked.</nowiki>

If the :candidate capability is supported, and it is not already locked,
then it may usually be locked. However, <nowiki>the <candidate>
configuration can only be locked if there are no edits already contained
within it. </nowiki><nowiki>A <discard-changes> operation may be needed
to clear any leftover edits, if this operation fails with a
'resource-denied' error instead of a 'lock-denied' error.</nowiki>

<nowiki>If the session holding the lock is terminated for any reason,
the lock will be released, as if the <unlock> operation was
invoked.</nowiki>


<center>'''<nowiki><lock> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|-
|  Capabilities optional:
|  :candidate:startup

|}
Mandatory Parameters:

* '''target'''
** type: container with 1 of N choice of leafs
** This parameter specifies the name of the target database to be
locked.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: none
*** '''startup'''
**** type: empty
**** capabilities needed: startup

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

* <nowiki>lock-denied (lock already held by <session-id> in the
<error-info>)</nowiki>
* <nowiki>resource-denied (candidate is dirty; <discard-changes>
needed)</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="62"> 
    <nowiki><nc:lock> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
    <nowiki></nc:lock> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="62"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <no-op> ===
<nowiki>The <no-op> operation is used for debugging and performance
testing purposes.</nowiki>

This operation does not do anything. <nowiki>It simply returns <ok/>,
unless any parameters are provided.</nowiki>


<center>'''<nowiki><no-op> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-system.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="63"> 
    <nowiki><nd:no-op xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="63"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <partial-lock> ===
<nowiki>The <partial-lock> operation is used to lock part of the
<running> database.</nowiki>

Refer to RFC 5717 or the''' ietf-netconf-partial-lock.yang''' module for
details on this operation.


<center>'''<nowiki><partial-lock> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  data

|-
|  YANG file:
|  ietf-netconf-partial-lock.yang

|-
|  Capabilities needed:
|  :partial-lock

|}
Mandatory Parameters:

* '''<nowiki><select></nowiki>'''
** type: XPath 1.0 string
** This parameter contains an XPath expression for a node-set result,
identifying the database nodes to lock.
** One of more instances of this parameter is required.
** The server allows relaxed XPath syntax. If prefixes are used, then a
proper namespace declaration must be present in the request. If prefixes
are not used, then any available namespace that matches the local name
will be used.

Optional Parameters:

* none

Returns:

* '''<nowiki><lock-id></nowiki>'''
** type: uint32 (range 1 .. MAX_UINT)
** <nowiki>This data identifies the lock ID to use when releasing the
lock with the <partial-unlock> operation.</nowiki>
** There will be one of these elements in the reply.
* '''<nowiki><locked-node></nowiki>'''
** type: instance-identifier
** This data identifies a locked node as a result of the request.
** There will be one or more of these elements in the reply.

Possible Operation Errors:

* access denied, in-use, resource-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="260"> 
    <nowiki><pl:partial-lock
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"> </nowiki>
       <nowiki><pl:select>//interface</pl:select> </nowiki>
    <nowiki></pl:partial-lock> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="260"
xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> 
    <nowiki><pl:lock-id
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">1</pl:lock-id>
</nowiki>
    <nowiki><pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='virbr0']</pl:locked-node>
</nowiki>
    <nowiki><pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='eth0']</pl:locked-node>
</nowiki>
    <nowiki><pl:locked-node
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='lo']</pl:locked-node>
</nowiki>
 <nowiki></nc:rpc-reply> </nowiki>

=== <partial-unlock> ===
<nowiki>The <partial-unlock> operation is used to unlock part of the
<running> database that was previously locked with the <partial-lock>
operation. </nowiki><nowiki>Only the session that called <partial-lock>
can release the lock with this operation.</nowiki>

Refer to RFC 5717 or the''' ietf-netconf-partial-lock.yang''' module for
details on this operation.


<center>'''<nowiki><partial-unlock> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  ietf-netconf-partial-lock.yang

|-
|  Capabilities needed:
|  :partial-lock

|}
Mandatory Parameters:

* '''<nowiki><lock-id></nowiki>'''
** type: unit32 (1 .. MAX_UINT)
** This parameter contains the lock ID of the partial lock to release.
** One of more instances of this parameter is required.
** The server allows relaxed XPath syntax. If prefixes are used, then a
proper namespace declaration must be present in the request. If prefixes
are not used, then any available namespace that matches the local name
will be used.

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access denied, invalid-value

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="263"> 
    <nowiki><pl:partial-unlock
xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"> </nowiki>
       <nowiki><pl:lock-id>1</pl:lock-id> </nowiki>
    <nowiki></pl:partial-unlock> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="263"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply> </nowiki>

=== <restart> ===
<nowiki>The <restart> operation is used to restart the
</nowiki>'''netconfd''' server.

By default, only the 'superuser' account is allowed to invoke this
operation.

If permission is granted, then the current NETCONF session will dropped,
during the server restart.


<center>'''<nowiki><restart> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  none

|-
|  YANG file:
|  yuma-system.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* none; session will be dropped upon success

Possible Operation Errors:

* access denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="63"> 
    <nowiki><nd:restart
xmlns:nd="http://netconfcentral.org/ns/netconfd"/> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki>[no reply will be sent; session will be dropped
instead.]</nowiki>

=== <set-log-level> ===
<nowiki>The <set-log-level> operation is used to configure the server
logging verbosity level.</nowiki>

Only the designated superuser user can invoke this operation by default.


<center>'''<nowiki><set-log-level> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-system.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* '''<nowiki><log-level></nowiki>'''
** type: enumeration (off, error, warn, info, debug, debug2, debug3)
** default: none
** This parameter specifies the server logging verbosity level.

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><myses:set-my-session
xmlns:myses="http://netconfcentral.org/ns/mysession"> </nowiki>
       <nowiki><myses:indent>4</myses:indent></nowiki>
       <nowiki><myses:linesize>64</myses:linesize></nowiki>
       <nowiki><myses:with-defaults>trim</myses:with-defaults> </nowiki>
    <nowiki></myses:set-my-session> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="3"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <set-my-session> ===
<nowiki>The <set-my-session> operation is used to configure the session
customization data for the current session.</nowiki>

The session indent amount, line size, and default behavior for the
with-defaults parameter can be controlled at this time.

<center>'''<nowiki><set-my-session> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  3

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-mysession.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* '''<nowiki><indent></nowiki>'''
** type: uint32 (range 0 .. 9)
** default: 3 (can be changed with the '''--indent''' configuration
parameter)
** This parameter specifies the desired indent amount for the session.
* '''<nowiki><linesize></nowiki>'''
** type: uint32 (range 40 .. 1024)
** default: 72
** This parameter specifies the desired line length for the session.
* '''<nowiki><with-defaults></nowiki>'''
** type: enumeration (report-all report-all-tagged trim explicit)
** default: report-all (can be changed with the '''--default-style
'''configuration parameter)
** This parameter specifies the desired default with-defaults behavior
for the session. The server-wide default value is set with the
'''--default-style '''configuration parameter.

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access-denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><myses:set-my-session
xmlns:myses="http://netconfcentral.org/ns/mysession"> </nowiki>
       <nowiki><myses:indent>4</myses:indent></nowiki>
       <nowiki><myses:linesize>64</myses:linesize></nowiki>
       <nowiki><myses:with-defaults>trim</myses:with-defaults> </nowiki>
    <nowiki></myses:set-my-session> </nowiki>
 <nowiki></nc:rpc></nowiki>


Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="3"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <shutdown> ===
<nowiki>The <shutdown> operation is used to shut down the
</nowiki>'''netconfd''' server.

By default, only the 'superuser' account is allowed to invoke this
operation.

If permission is granted, then the current NETCONF session will dropped,
during the server shutdown.


<center>'''<nowiki><shutdown> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  Return type:
|  none

|-
|  YANG file:
|  yuma-system.yang

|-
|  Capabilities needed:
|  none

|}
Mandatory Parameters:

* none

Optional Parameters:

* none

Returns:

* none; session will be dropped upon success

Possible Operation Errors:

* access denied

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="1"> 
    <nowiki><nd:shutdown
xmlns:nd="http://netconfcentral.org/ns/netconfd"/> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki>[no reply will be sent; session will be dropped
instead.]</nowiki>

=== <unlock> ===
<nowiki>The <unlock> operation is used to release a global lock held by
the current session.</nowiki>

<nowiki>The specified configuration database must be locked, or a
'no-access' <error-app-tag> and an <error-message> of
'wrong-config-state' will be returned.</nowiki>

<nowiki>If the <candidate> configuration contains any edits that have
not been committed, then these edits will all be lost if the <unlock>
operation is invoked. </nowiki><nowiki>A <discard-changes> operation is
performed automatically by the server when the <candidate> database is
unlocked.</nowiki>


<center>'''<nowiki><unlock> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  none

|-
|  Capabilities optional:
|  :candidate:startup

|}
Mandatory Parameters:

* '''target'''
** type: container with 1 of N choice of leafs
** This parameter specifies the name of the target database to be
unlocked.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: none
*** '''startup'''
**** type: empty
**** capabilities needed: startup

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access denied
* no-access (database not locked)
* invalid-value (database not supported)

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="65"> 
    <nowiki><nc:unlock> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
    <nowiki></nc:unlock> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="65"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== <validate> ===
<nowiki>The <validate> operation is used to perform the <commit>
validation tests against a database or some in-line configuration
data.</nowiki>


<center>'''<nowiki><validate> operation</nowiki>'''</center>



{| class=wikitable border="1"
|  Min parameters:
|  1

|-
|  Max parameters:
|  1

|-
|  Return type:
|  status

|-
|  YANG file:
|  yuma-netconf.yang

|-
|  Capabilities needed:
|  :validate

|-
|  Capabilities optional:
|  :candidate:startup

|}
Mandatory Parameters:

* '''target'''
** type: container with 1 of N choice of leafs
** This parameter specifies the name of the target database, or the
in-line configuration data, that should be validated.
** container contents: 1 of N:
*** '''candidate'''
**** type: empty
**** capabilities needed:''' ''':candidate
*** '''running'''
**** type: empty
**** capabilities needed: none
*** '''startup'''
**** type: empty
**** capabilities needed: startup
*** '''config'''
**** type anyxml
**** capabilities needed: none

Optional Parameters:

* none

Returns:

* <nowiki><ok/></nowiki>

Possible Operation Errors:

* access denied
* <nowiki><commit> validation errors</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="76"> 
    <nowiki><nc:validate> </nowiki>
       <nowiki><nc:source> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:source> </nowiki>
    <nowiki></nc:validate> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="76"> 
    <nowiki><nc:ok/> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

== Access Control ==
The '''netconfd''' access control data model is defined in
'''yuma-nacm.yang'''.

The '''nacm:secure '''and''' nacm:very-secure''' extensions also affect
access control. If present in the YANG definition, then the default
behavior (when no rule is found) is not followed. Instead, the super
user account must be used to allow default access.

There are 3 types of access control rules that can be defined:

# module rule
# RPC operation rule
# database rule

Rules apply to one or more groups.

Each group contains zero or more user names.

Database rules are applied top-down, at every level.

The user needs permission for the requested access (read or write) for
all referenced nodes within the database. For example, if there was a
leaf from module X that augments a container in module Y, the user would
need permission to access the container from module Y, and then
permission to access the leaf from module X.

The NACM data model can be used without any configuration at all. Refer
to the section on access control modes for more details.

[[Image:]]

Normally, some configuration is required:

* groups: configure one or more administrative groups
* rules: configure one or more access control rules

The entire '''/nacm''' subtree is tagged as '''nacm:very-secure'''. By
default, only the super-user account can read or write any of its
contents. It is suggested that even read access to this data structure
be controlled carefully at all times.

=== NACM Module Structure ===
The '''/nacm''' subtree consists of 3 read-only leafs and 2 containers:

* leaf '''<nowiki><enable-nacm></nowiki>''': enable or disable access
control enforcement
* leaf'''<nowiki> <read-default></nowiki>''': permit or deny read access
when no rule found
* leaf'''<nowiki> <write-default></nowiki>''': permit or deny write
access when no rule found
* leaf'''<nowiki> <exec-default></nowiki>''': permit or deny execute
access when no rule found
* leaf '''<nowiki><denied-rpcs></nowiki>''': read-only counter of denied
RPC operation requests
* leaf '''<nowiki><denied-data-writes></nowiki>''': read-only counter of
denied database write requests
* container'''<nowiki> <groups></nowiki>''': need 1 or more '''group'''
list entries in order for '''rules''' to have any effect
** list'''<nowiki> <group></nowiki>''': principle that is assigned
access privileges
*** leaf'''<nowiki> <group-identity></nowiki>''': group identifier
string
*** <nowiki>leaf-list <</nowiki>'''user-name>''': leaf-list of users
that belong to the group
* container'''<nowiki> <rules></nowiki>''':
** list'''<nowiki> <module-rule></nowiki>''': an access rule for an
entire module namespace
*** leaf'''<nowiki> <module-name></nowiki>'''<nowiki>: [key] name of the
YANG module associated with the rule</nowiki>
*** leaf'''<nowiki> <allowed-rights></nowiki>'''<nowiki>: [key]
privileges granted to all groups associated with the rule</nowiki>
*** leaf-list'''<nowiki> <allowed-group></nowiki>''': leaf-list of one
or more group identifiers that are associated with the rule
*** leaf'''<nowiki> <comment></nowiki>''': comment string for the rule
(ignored by the server)
** list'''<nowiki> <rpc-rule></nowiki>''': an access rule for one
specific protocol operation, defined in a YANG rpc statement.
*** leaf'''<nowiki> <rpc-module-name></nowiki>'''<nowiki>: [key] name of
the YANG module associated with the rule</nowiki>
*** <nowiki>leaf <</nowiki>'''rpc-name>:'''<nowiki> [key] name of the
RPC operation associated with the rule</nowiki>
*** leaf'''<nowiki> <allowed-rights></nowiki>'''<nowiki>: [key]
privileges granted to all groups associated with the rule</nowiki>
*** leaf-list'''<nowiki> <allowed-group></nowiki>''': leaf-list of one
or more group identifiers that are associated with the rule
*** leaf'''<nowiki> <comment></nowiki>''': comment string for the rule
(ignored by the server)
** list'''<nowiki> <data-rule></nowiki>''': an user-ordered access rule
for one or more database subtrees.
*** leaf'''<nowiki> <name></nowiki>'''<nowiki>: [key] arbitrary name
string for the rule</nowiki>
*** leaf'''<nowiki> <path></nowiki>''': XPath expression for the
database instances which are associated with the rule
*** leaf'''<nowiki> <allowed-rights></nowiki>''': privileges granted to
all groups associated with the rule
*** leaf-list'''<nowiki> <allowed-group></nowiki>''': leaf-list of one
or more group identifiers that are associated with the rule
*** leaf'''<nowiki> <comment</nowiki>''':> comment string for the rule
(ignored by the server)
** list'''<nowiki> <notification-rule></nowiki>''': an user-ordered
access rule for one notification events.
*** leaf'''<nowiki> <notification-module-name></nowiki>'''<nowiki>:
[key] name of the YANG module associated with the rule</nowiki>
*** <nowiki>leaf <</nowiki>'''notification-name>:'''<nowiki> [key] name
of the notification event type associated with the rule</nowiki>
*** leaf'''<nowiki> <allowed-rights></nowiki>'''<nowiki>: [key]
privileges granted to all groups associated with the rule</nowiki>
*** leaf'''<nowiki> <allowed-rights></nowiki>''': privileges granted to
all groups associated with the rule
*** leaf-list'''<nowiki> <allowed-group></nowiki>''': leaf-list of one
or more group identifiers that are associated with the rule
*** leaf'''<nowiki> <comment</nowiki>''':> comment string for the rule
(ignored by the server)

=== Users and Groups ===
Access rights in NACM are given to groups.

A group entry consists of a group identifier and a list of user names
that are members of the group.

A group is named with is a YANG identity, which has a base of
'nacmRoot':

 
     identity nacmGroups {
         description 
         "Root of all NETCONF Administrative Groups";
     }


There are 3 hard-wired group names that can be used:

* nacm:admin
* nacm:monitor
* nacm:guest

Any module can define an extension identity for the 'nacmGroups' base
type, and use it as a group name. There are no special semantics
associated with any particular group name.


 
     import nacm { prefix nacm; }
 
     identity mygroup {
         description 
         "My special administrator's group.";
         base nacm:nacmGroups;
     }

By default, there are no groups created. Each '''/nacm/groups/group'''
entry must be created by the client. There is no user name table either.
It is assumed that the operator will know which user names are valid
within each managed device.

=== Creating New Groups ===
<nowiki>The <edit-config> operation can be used to create new group
entries.</nowiki>

<nowiki>Each group is identified only by its <groupIdentity>
leaf.</nowiki>

A user name can appear within the same group zero or one times.

A user name can appear in zero or more groups.

When a user is a member of multiple groups, all these groups will be
used to match against rules, in a conceptual 'OR' expression. <nowiki>If
any of these groups matches one of the <allowed-group> leaf-list nodes
within one of the 3 rule types, then that rule will be the one that is
used. </nowiki>Rules are always searched in the order they are entered,
even the system-ordered lists.

The path to the group element is
'''/nacm:nacm/nacm:groups/nacm:group.'''

<nowiki>The following <edit-config> example shows how a group can be
defined. </nowiki>The group name is 'nacm:guest',and the users 'fred'
and 'barney' are the initial members of this group.


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm"> </nowiki>
             <nowiki><nacm:groups> </nowiki>
                <nowiki><nacm:group </nowiki> nc:operation="create"> 
                  
<nowiki><nacm:group-identity>nacm:guest</nacm:group-identity> </nowiki>
                  
<nowiki><nacm:user-name>fred</nacm:user-name></nowiki>
                  
<nowiki><nacm:user-name>barney</nacm:user-name></nowiki>
                <nowiki></nacm:group> </nowiki>
             <nowiki></nacm:groups> </nowiki>
          <nowiki></nacm:nacm> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>


=== Access Control Modes ===
The''' --access-control '''configuration parameter is used to globally
enable or disable the access control system. It cannot be changed at
run-time, or through a NETCONF session.

* '''off''': no access control enforcement is done at all.
* '''disabled''': all '''nacm:secure''' and '''nacm:very-secure'''
tagged objects will require the super user account to access, but no
other access control enforcement will be done.
* '''permissive''': all '''nacm:very-secure''' objects will require
super user account to read. No other read access enforcement will be
done. Write and exec access will be checked.
* '''enforcing''': all access control enforcement will be checked. This
is the default behavior.

=== Permissions ===
There are 3 types of access permissions defined:

# '''read''': retrieval of any kind
# '''write''': modification of any kind
# '''exec''': right to invoke an RPC operation

<nowiki>The <allowed-rights> object in each of the 3 access control rule
entries is a 'bits' leaf, which is allowed to contain any of these
string tokens, or none of them to deny all access to a set of
groups.</nowiki>

<nowiki>When a rule is found which matches the current request, the
<allowed-rights> leaf will be used to grant permission or not.
</nowiki>If the bit for the requested operation is present, then the
request is permitted. If the bit is not present, then the request is
denied.

=== Special YANG Extensions For Access Control ===
There are 3 YANG language extensions defined that can be used to force
access control behavior for specific data nodes in the configuration
database.

# '''nacm:secure''' (no parameter)If present in a data node statement,
this extension will cause the write default to be ignored, and any write
access to instances of this object will be rejected with an
'access-denied' error unless there is an explicit NACM rule allowing
write access to the user session. If present in an 'rpc' statement, then
exec access will be denied unless there is an explicit NACM rule
granting exec access.
# '''nacm:very-secure''' (no parameter)<nowiki>If present in a data node
statement, this extension will cause the read and write defaults to be
ignored, and any write access to instances of this object will be
rejected with an 'access-denied' error unless there is an explicit NACM
rule allowing write access to the user session. Read access will be
denied, which causes that data to be removed from the <rpc-reply>.
</nowiki>If present in an 'rpc' statement, then exec access will be
denied unless there is an explicit NACM rule granting exec access.
# '''ncx:user-write''' (parameter: permitted, type: bits: create,
update, delete)
# Used within database configuration data definition statements to
control user write access to the database object containing this
statement. The 'permitted' argument is a list of operations that users
are permitted to invoke for the specified node. These permissions will
over-ride all NACM access control rules, even if NACM is disabled.To
dis-allow all user access, provide an empty string for the 'permitted'
parameter.<br/> To allow only create and delete user access, provide the
string 'create delete' for the parameter. Use this for YANG database
objects that cannot be changed once they are set.

=== Default Enforcement Behavior ===
Each access type has a default behavior if no rule is found and no
special YANG extensions apply:

* read default: permit
* write default: deny
* exec default: permit

These defaults can be changed by the server developer, by modifying the
YANG definitions in '''yuma-nacm.yang'''. If the data node object
definition contains the special YANG extensions described in the
previous section, then the extension will define default access and the
NACM default access rule will not be used.

=== Access Control Algorithm ===
The following logic represents the steps taken during access control
enforcement.


'''Phase 1: RPC Operation Access'''

* Step 1) If the '''--access-control''' configuration parameter is set
to 'off' then grant access and exit.
* Step 2) If the user name matches the '''--superuser''' configuration
variable (or the default 'superuser' if not set), then grant access and
exit.
* <nowiki>Step 3) If the RPC operation requested is the NETCONF
<close-session> operation, then grant access and exit.</nowiki>
* Step 4) If the''' --access-control''' configuration parameter is set
to 'disabled':
** a) If the requested RPC operation is tagged as '''nacm:secure '''or
'''nacm:very-secure''', then deny access, otherwise grant access, and
exit.
* Step 5) Retrieve all the NACM groups that this user is found within.
** If there are no groups found:
*** a) If the requested RPC operation is tagged as '''nacm:secure '''or
'''nacm:very-secure''', then deny access and exit.
*** <nowiki>b) If the <exec-default> leaf is set to 'permit' then grant
access, otherwise deny access, and exit.</nowiki>
** If there are any groups found, then proceed to step 6.
* Step 6) Check if there are any''' /nacm/rules''' nodes configured.
** <nowiki>If there are no rules configured, then if the <exec-default>
leaf is set to 'permit' then grant access, otherwise deny access, and
exit.</nowiki>
** <nowiki>If there are some entries within the <rules> container, then
proceed to step 7.</nowiki>
* Step 7) Check for any '''/nacm/rules/rpc-rule'''<nowiki> entries that
contain an <allowed-group> with the same value as one of the groups
found in step 5, and is also for the requested RPC operation.
</nowiki>The first entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'exec' bit.</nowiki>
**** If the 'exec' bit is found, then grant access, otherwise deny
access, and exit.
*** <nowiki>If a matching <rpc-rule> entry is not found, then proceed to
step 8.</nowiki>
* Step 8) Check for any '''/nacm/rules/module-rule'''<nowiki> entries
that contain an <allowed-group> with the same value as one of the groups
found in step 5, and is also for same module as the requested RPC
operation. </nowiki>The first entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'exec' bit.</nowiki>
**** If 'exec' bit is found, then grant access, otherwise deny access,
and exit.
*** <nowiki>If a matching <module-rule> entry is not found, then proceed
to step 9.</nowiki>
* <nowiki>Step 9) If the <exec-default> leaf is set to 'permit' then
grant access, otherwise deny access.</nowiki>
** Continue to phase 2a if any read access, or phase 2b if any write
access to the NETCONF database contents is requested on behalf of the
specific RPC operation.

'''Phase 2a: Database Read and Notification Access'''

* Step 10) If the user name matches the '''--superuser''' configuration
variable (or the default 'superuser' if not set), then grant access and
exit.
* Step 11) Check the access control mode:
** a) If the '''--access-control''' configuration parameter is set to
'permissive'
*** If the requested object is tagged as '''nacm:very-secure''', then
deny access, otherwise grant access, and exit
** b) Otherwise, this must be normal 'enforcing' mode, so proceed to
step 12.
* Step 12) Make sure there are some groups and rules
** a) If there were no groups found in step 5, or no rules found in step
6, then:
*** If the requested object is tagged as '''nacm:very-secure''', then
deny access, otherwise:
**** <nowiki>If the <read-default> is set to 'permit', then grant
access, otherwise deny access, and exit.</nowiki>
** b) If there are some groups and rules, then proceed to step 13 to
start checking access control rules.
* Step 13) Check for any '''/nacm/rules/data-rule'''<nowiki> entries
that contain a <path> expression that evaluates to an XPath node-set
that contains the requested database node, and the <allowed-group>
leaf-list contains an entry with the same value as one of the groups
found in step 5. </nowiki>The first such entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'read' bit.</nowiki>
**** If the 'read' bit is found, then grant access, otherwise deny
access, and exit.
*** If an entry is not found, then proceed to step 14.
* Step 14) Check for any '''/nacm/rules/module-rule'''<nowiki> entries
that contain an <allowed-group> with the same value as one of the groups
found in step 5, and is also for the same module as the requested
database node. </nowiki>The first entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'read' bit.</nowiki>
**** If the 'read' bit is found, then grant access, otherwise deny
access, and exit.
*** If an entry is not found, then proceed to step 15.
* <nowiki>Step 15) If the <read-default> leaf is set to 'permit' then
grant access, otherwise deny access, and exit.</nowiki>

'''Phase 2b) Database Write Access'''

* Step 16) If the user name matches the '''--superuser''' configuration
variable (or the default 'superuser' if not set), then grant access and
exit.
* Step 17) Make sure there are some groups and rules
** a) If there were no groups found in step 5, or no rules found in step
6, then:
*** If the requested object is tagged as '''nacm:secure '''or'''
nacm:very-secure''', then deny access, otherwise:
**** <nowiki>If the <write-default> is set to 'permit', then grant
access, otherwise deny access, and exit.</nowiki>
** b) If there are some groups and rules, then proceed to step 18 to
start checking access control rules.
* Step 18) Check for any '''/nacm/rules/data-rule'''<nowiki> entries
that contain a <path> expression that evaluates to an XPath node-set
that contains the requested database node, and the <allowed-groups>
leaf-list contains an entry with the same value as one of the groups
found in step 5. </nowiki>The first such entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'write' bit.</nowiki>
**** If the 'write' bit is found, then grant access, otherwise deny
access, and exit.
*** If an entry is not found, then proceed to step 19.
* Step 19) Check for any '''/nacm/rules/module-mule'''<nowiki> entries
that contain an <allowed-group> with the same value as one of the groups
found in step 5, and is also for the same module as the requested
database node. </nowiki>The first entry found will be used.
** 
*** <nowiki>If an entry is found, then check its <allowed-rights> leaf
for the 'write' bit.</nowiki>
**** If the 'write' bit is found, then grant access, otherwise deny
access, and exit.
*** If an entry is not found, then proceed to step 20.
* <nowiki>Step 20) If the <write-default> leaf is set to 'permit' then
grant access, otherwise deny access, and exit.</nowiki>

=== Module Access Control Rules ===
The''' /nacm/rules/module-rule''' data structure is used to configure
access for any object or RPC operation from a specific YANG module. If
the module namespace URI is the same as the XML namespace used in the
NETCONF PDU, then the module rule is considered a match.

<nowiki>Multiple instances can appear for a single module, as long as
the <allowed-access> key leaf value is different in each entry.
</nowiki>This allows different groups to get different access to the
same module (e.g., read vs. read and write).

<nowiki>There is no way to move <module-rule> entries around, once they
are created.</nowiki>

If a group appears in multiple entries for the same module name, then
the first one encountered will be used. <nowiki>Entries are checked in
the same order they are returned in a <get-config> reply
message.</nowiki>


<nowiki>The following example shows an <edit-config> operation which
creates 2 <moduleRule> entries, for the following
configuration:</nowiki>

* the 'admin' group is allowed to read and write the NACM module.
* the 'monitor' group is allowed to read the NACM module.<br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="4"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm"> </nowiki>
             <nowiki><nacm:rules> </nowiki>
                <nowiki><nacm:module-rule </nowiki>
nc:operation="create"> 
                   <nowiki><nacm:module-name>nacm</nacm:module-name>
</nowiki>
                   <nowiki><nacm:allowed-rights>read
write</nacm:allowed-rights> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:admin</nacm:allowed-group> </nowiki>
                <nowiki></nacm:module-rule> </nowiki>
                <nowiki><nacm:module-rule </nowiki>
nc:operation="create"> 
                   <nowiki><nacm:module-name>nacm</nacm:module-name>
</nowiki>
                  
<nowiki><nacm:allowed-rights>read</nacm:allowed-rights> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:monitor</nacm:allowed-group> </nowiki>
                <nowiki></nacm:module-rule> </nowiki>
             <nowiki></nacm:rules> </nowiki>
          <nowiki></nacm:nacm> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

=== RPC Access Control Rules ===
The''' /nacm/rules/rpc-rule''' data structure is used to configure
access for a specific RPC operation from a specific YANG module.
<nowiki>If the module namespace URI for the <rpc-module-name> value is
the same as the XML namespace used in the NETCONF PDU,and the
<rpc--name> value is the same as the RPC method name, then the RPC rule
is considered a match.</nowiki>

<nowiki>Multiple instances can appear for a single RPC operation, as
long as the <allowed-access> key leaf value is different in each entry.
</nowiki>This allows different groups to get different access to the
same operation (e.g., exec vs. no access).

<nowiki>There is no way to move <rpc-rule> entries around, once they are
created.</nowiki>

If a group appears in multiple entries for the same RPC operation, then
the first one encountered will be used. <nowiki>Entries are checked in
the same order they are returned in a <get-config> reply
message.</nowiki>

<nowiki>If the 'read' or 'write' access bits are set in the
<allowed-rights> key leaf, then they will be ignored. </nowiki>This will
not cause an error, but it these bits have no effect within an RPC rule.


<nowiki>The following example shows an <edit-config> operation which
creates 2 <module-rule> entries, for the following
configuration:</nowiki>

* <nowiki>the 'admin' and 'monitor' groups are allowed to execute the
<get-config> operation.</nowiki>
* the 'guest' group is '''not'''<nowiki> allowed to execute the
<get-config> operation</nowiki><br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="5"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm"> </nowiki>
             <nowiki><nacm:rules> </nowiki>
                <nowiki><nacm:rpc-rule </nowiki> nc:operation="create"> 
                  
<nowiki><nacm:rpc-module-name>netconf</nacm:rpc-module-name> </nowiki>
                   <nowiki><nacm:rpc--name>get-config</nacm:rpc--name>
</nowiki>
                  
<nowiki><nacm:allowed-rights>exec</nacm:allowed-rights> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:admin</nacm:allowed-group> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:monitor</nacm:allowed-group> </nowiki>
                <nowiki></nacm:rpc-rule> </nowiki>
                <nowiki><nacm:rpc-rule </nowiki> nc:operation="create"> 
                  
<nowiki><nacm:rpc-module-name>netconf</nacm:rpc-module-name> </nowiki>
                   <nowiki><nacm:rpc--name>get-config</nacm:rpc--name>
</nowiki>
                   <nowiki><nacm:allowed-rights/></nowiki>
                  
<nowiki><nacm:allowed-group>nacm:guest</nacm:allowed-group> </nowiki>
                <nowiki></nacm:rpc-rule> </nowiki>
             <nowiki></nacm:rules> </nowiki>
          <nowiki></nacm:nacm> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

=== Data Access Control Rules ===
The''' /nacm/rules/data-rule''' data structure is used to configure
access for a specific set of database nodes (or notification payload
nodes). <nowiki>If the requested node in contained within the node-set
result of the <path> XPath path expression, then the data rule is
considered a match.</nowiki>

<nowiki>Multiple instances of the same <path> expression (or equivalent
expressions), can appear at any time, and in any order.</nowiki>

<nowiki>The <path> leaf is not allowed to contain an arbitrary XPath
expression (at this time). </nowiki>Instead, an
'''ncx:schema-instance''' string is allowed. <nowiki>This has the same
syntax as a YANG instance-identifier built-in type, except that the key
leaf predicates (e.g., [name='eth0']) are optional instead of mandatory.
</nowiki>A missing key leaf predicate indicates that all instances of
that key leaf are going to match the data rule.

<nowiki>This is a user-created list, and the key leaf is the arbitrary
<name> field. </nowiki>Use the YANG 'insert' operation to add data rules
in some order other than 'last'. <nowiki>Entries are checked in the same
order they are returned in a <get-config> reply message.</nowiki>

If a group appears in multiple entries, then the first one that produces
a result node-set with a matching node wiill be used. 

<nowiki>If the 'exec' access bit is set in the <allowed-rights> key
leaf, then it will be ignored. </nowiki>This will not cause an error,
but it this bit has no effect within a data rule.

<nowiki>The following example shows an <edit-config> operation which
creates 3 <data-rule> entries, for the following configuration:</nowiki>

* the 'admin' group is allowed to read or write all interfaces.
* the 'monitor' group is allowed to read the 'eth0' interface
* the 'guest' group is not allowed to read any interfaces
information<br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="3"> 
    <nowiki><nc:edit-config> </nowiki>
       <nowiki><nc:target> </nowiki>
          <nowiki><nc:candidate/> </nowiki>
       <nowiki></nc:target> </nowiki>
       <nowiki><nc:default-operation>none</nc:default-operation>
</nowiki>
       <nowiki><nc:config> </nowiki>
          <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm"> </nowiki>
             <nowiki><nacm:rules> </nowiki>
                <nowiki><nacm:data-rule </nowiki> nc:operation="create">

                   <nowiki><nacm:name>itf-1</nacm:name> </nowiki>
                   <nowiki><nacm:path </nowiki>
                     
xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
                        /if:interfaces/if:interface
                   <nowiki></nacm:path> </nowiki>
                   <nowiki><nacm:allowed-rights>read
write</nacm:allowed-rights> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:admin</nacm:allowed-group> </nowiki>
                   <nowiki><nacm:comment></nowiki>
                      let admin group read and write all interfaces
                   <nowiki></nacm:comment> </nowiki>
                <nowiki></nacm:data-rule> </nowiki>
                <nowiki><nacm:data-rule </nowiki> nc:operation="create">

                   <nowiki><nacm:name>itf-2</nacm:name> </nowiki>
                   <nowiki><nacm:path </nowiki>
                     
xmlns:if="http://netconfcentral.org/ns/interfaces">
                       
<nowiki>/if:interfaces/if:interface[if:name='eth0']</nowiki>
                   <nowiki></nacm:path> </nowiki>
                  
<nowiki><nacm:allowed-rights>read</nacm:allowed-rights> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:monitor</nacm:allowed-group> </nowiki>
                   <nowiki><nacm:comment></nowiki>
                      let monitor group read interface 'eth0'
                   <nowiki></nacm:comment> </nowiki>
                <nowiki></nacm:data-rule> </nowiki>
                <nowiki><nacm:data-rule </nowiki> nc:operation="create">

                   <nowiki><nacm:name>itf-3</nacm:name> </nowiki>
                   <nowiki><nacm:path </nowiki>
                     
xmlns:if="http://netconfcentral.org/ns/interfaces">
                        /if:interfaces
                   <nowiki></nacm:path> </nowiki>
                   <nowiki><nacm:allowed-rights/> </nowiki>
                  
<nowiki><nacm:allowed-group>nacm:guest</nacm:allowed-group> </nowiki>
                   <nowiki><nacm:comment></nowiki>
                      do not let guest group read any interfaces info
                   <nowiki></nacm:comment> </nowiki>
                <nowiki></nacm:data-rule> </nowiki>
             <nowiki></nacm:rules> </nowiki>
          <nowiki></nacm:nacm> </nowiki>
       <nowiki></nc:config> </nowiki>
    <nowiki></nc:edit-config> </nowiki>
 <nowiki></nc:rpc> </nowiki>

== Monitoring ==
<nowiki>The <get> and <get-config> operations are fully supported for
retrieving data from the <candidate> and <running> configuration
databases.</nowiki>

<nowiki>The <get-config> operation is not supported for the <startup>
configuration.</nowiki>

<nowiki>The <copy-config> operation is only supported copying the
<running> configuration to the <startup> configuration.</nowiki>

If the NACM access control policy denies permission to read a particular
node, then that node is silently skipped in the output. No error or
warning messages will be generated.

client applications should be prepared to receive XML subtrees that have
been pruned by access control. <nowiki>The <data> element will always be
present, so an empty <data/> element indicates that no data was
returned, either because the <filter> did not match, or because access
control pruned the requested nodes.</nowiki>


There are really five types of filters available for retrieval
operations:


<center>'''Filter Types'''</center>



{| class=wikitable border="1"
|  <center>'''type'''</center>
|  <center>'''description'''</center>

|-
|  is_config()
|  <nowiki>Choose the <get>operation for all objects, or <get-config>
for just config=true objects</nowiki>

|-
|  is_default()
|  <nowiki>Set the <with-defaults> parameter to 'trim'</nowiki>

|-
|  is_client_set()
|  <nowiki>Set the <with-defaults> parameter to 'explicit'</nowiki>

|-
|  subtree filtering
|  Use 

<nowiki><filter type="subtree"></nowiki>

// some-xml-subtree 

<nowiki></filter></nowiki>

<nowiki>to retrieve portions of the <candidate> or <running>
configurations.</nowiki>

|-
|  XPath filtering
|  Use 

<nowiki><filter type="xpath"</nowiki>

select="expr"/> 

<nowiki>to retrieve portions of the <candidate> or <running>
configurations.</nowiki>

|}
=== Using Subtree Filters ===
The subtree filtering feature is fully supported.

<nowiki>The order of nodes within the <filter> element is not relevant.
</nowiki><nowiki>Data returned in the <rpc-reply> should follow the same
top-level order as the request, but this should not be relied on to
always be the case.</nowiki>

Duplicate or overlapping subtrees within the request will be combined in
the output, so the common ancestor nodes are not duplicated in the
reply.

XML namespaces are optional to use:

* If there is no namespace in affect for a filter component, or the
'NETCONF' namespace is in effect, the server will attempt to find any
top-level data node which matches.
* <nowiki>Namespaces within descendant nodes of the <filter> node
children are inherited from their parent. </nowiki>If none is in effect,
then the first matching child node for the current parent node will be
used.
* <nowiki>Invalid namespace errors for the <filter> element are
suppressed in the server. </nowiki>An invalid namespace or unknown
element is simply a 'no-match' condition.

For example, the following PDU would be valid, even though it is not
technically valid XML:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="8"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter></nowiki>
          '''<nowiki><nacm> </nowiki>'''
            <nowiki><rules/> </nowiki>
          <nowiki></nacm> </nowiki>
       <nowiki></nc:filter> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc></nowiki>

<nowiki>Note that there is no default namespace in effect for the <nacm>
subtree. </nowiki>However, the server will accept this filter as if the
yuma-nacm.yang module namespace was properly declared.

Subtree filters can select specific list entries using content match
nodes. <nowiki>The following example would return the entire contents of
the <interface> entry for 'eth0':</nowiki>


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="9"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="subtree"> </nowiki>
          <nowiki><if:interfaces
xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> </nowiki>
             <nowiki><if:interface> </nowiki>
                <nowiki><if:name>eth0</if:name> </nowiki>
             <nowiki></if:interface> </nowiki>
          <nowiki></if:interfaces> </nowiki>
       <nowiki></nc:filter> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc> </nowiki>

To retrieve only specific nodes (such as counters) from a single list
entry, use select nodes for the desired counter(s), and include a
content match node for each key leaf. A missing key leaf will match any
entry for that key.

<nowiki>The following example request shows how just the <inBytes> and
<outBytes> counters could be retrieved from the <interface> entry for
'eth0'.</nowiki>


Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="10"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="subtree"> </nowiki>
          <nowiki><if:interfaces
xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> </nowiki>
             <nowiki><if:interface> </nowiki>
                <nowiki><if:name>eth0</if:name> </nowiki>
                <nowiki><if:counters> </nowiki>
                   <nowiki><if:inBytes/> </nowiki>
                   <nowiki><if:outBytes/> </nowiki>
                <nowiki></if:counters> </nowiki>
             <nowiki></if:interface> </nowiki>
          <nowiki></if:interfaces> </nowiki>
       <nowiki></nc:filter> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="10"> 
    <nowiki><nc:data> </nowiki>
       <nowiki><if:interfaces
xmlns:if="http://netconfcentral.org/ns/interfaces"> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>eth0</if:name> </nowiki>
             <nowiki><if:counters> </nowiki>
                <nowiki><if:inBytes>290046042</if:inBytes> </nowiki>
                <nowiki><if:outBytes>112808406</if:outBytes> </nowiki>
             <nowiki></if:counters> </nowiki>
          <nowiki></if:interface> </nowiki>
       <nowiki></if:interfaces> </nowiki>
    <nowiki></nc:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== Using XPath Filters ===
The :xpath capability is fully supported, including the YANG extensions
to this capability.

The XPath 2.0 rule for default XML namespace behavior is used, not XPath
1.0 rules, as specified by the YANG language. This means that any module
with a node with the same local-name, in the same position in the schema
tree, will match a missing XML prefix. This allows much simpler
specification of XPath filters, but it may match more nodes than
intended. Remember that any nodes added via an external YANG augment
statement may have the same local-name, even though they are bound to a
different XML namespace.

<nowiki>If the XPath expression does not return a node-set result, then
the empty <data/> element will be returned in the <rpc-reply>.</nowiki>

<nowiki>If no nodes in the node-set result exist in the specified target
database, then an empty <data/> element will be returned in the
<rpc-reply>.</nowiki>

<nowiki>If a node in the result node-set matches a node in the target
database, then it is included in the <rpc-reply>,</nowiki>

If a node selected for retrieval are contained within a YANG list node,
then all the key leaf nodes for the specific list entry will be returned
in the response.

The powerful '//' operator (equivalent to "descendant-or-self::node()")
can be used to construct really simple XPath expressions.

The following example shows how a simple filter like '//name' will
return nodes from all over the database, yet they can all be fully
identified because the path from root is part of the response data.


Example Request:

* xget //name<br/> 


 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="43"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="xpath" select="//name"/> </nowiki>
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc>]]>]]> </nowiki>

Example Reply:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="43"> 
    <nowiki><nc:data> </nowiki>
       <nowiki><nacm:nacm
xmlns:nacm="http://netconfcentral.org/ns/nacm"> </nowiki>
          <nowiki><nacm:rules> </nowiki>
             <nowiki><nacm:data-rule> </nowiki>
                <nowiki><nacm:name>nacm-tree</nacm:name> </nowiki>
             <nowiki></nacm:data-rule> </nowiki>
             <nowiki><nacm:data-rule> </nowiki>
                <nowiki><nacm:name>itf-1</nacm:name> </nowiki>
             <nowiki></nacm:data-rule> </nowiki>
          <nowiki></nacm:rules> </nowiki>
       <nowiki></nacm:nacm> </nowiki>
       <nowiki><t:xpath.1 xmlns:t="http://netconfcentral.org/ns/test">
</nowiki>
          <nowiki><t:name>barney</t:name> </nowiki>
       <nowiki></t:xpath.1> </nowiki>
       <nowiki><if:interfaces
xmlns:if="http://netconfcentral.org/ns/interfaces"> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>lo</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>eth0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>virbr0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>pan0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
       <nowiki></if:interfaces> </nowiki>
       <nowiki><ns:netconf-state </nowiki>         
xmlns:ns="urn:ietf:params:xml:ns:netconf:monitoring"> 
          <nowiki><ns:datastores> </nowiki>
             <nowiki><ns:datastore> </nowiki>
                <nowiki><ns:name> </nowiki>
                   <nowiki><ns:candidate/> </nowiki>
                <nowiki></ns:name> </nowiki>
             <nowiki></ns:datastore> </nowiki>
             <nowiki><ns:datastore> </nowiki>
                <nowiki><ns:name> </nowiki>
                   <nowiki><ns:running/> </nowiki>
                <nowiki></ns:name> </nowiki>
             <nowiki></ns:datastore> </nowiki>
             <nowiki><ns:datastore> </nowiki>
                <nowiki><ns:name> </nowiki>
                   <nowiki><ns:startup/> </nowiki>
                <nowiki></ns:name> </nowiki>
             <nowiki></ns:datastore> </nowiki>
          <nowiki></ns:datastores> </nowiki>
       <nowiki></ns:netconf-state> </nowiki>
       <nowiki><manageEvent:netconf </nowiki>   
xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"> 
          <nowiki><manageEvent:streams> </nowiki>
             <nowiki><manageEvent:stream> </nowiki>
                <nowiki><manageEvent:name>NETCONF</manageEvent:name>
</nowiki>
             <nowiki></manageEvent:stream> </nowiki>
          <nowiki></manageEvent:streams> </nowiki>
       <nowiki></manageEvent:netconf> </nowiki>
    <nowiki></nc:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

In order to refine the previous filter to select nodes from just one
module, the use the XML prefix in the node identifier. <nowiki>The
example below selects only the <name> nodes from the interfaces
module.</nowiki>


Example Request:

* xget //if:name<br/> 


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
</nowiki>
    message-id="44"> 
    <nowiki><nc:get> </nowiki>
       <nowiki><nc:filter type="xpath" </nowiki>
          xmlns:if="http://netconfcentral.org/ns/interfaces" 
          select="//if:name"/> 
    <nowiki></nc:get> </nowiki>
 <nowiki></nc:rpc></nowiki>

Example Reply:

 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><nc:rpc-reply
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" </nowiki>
    message-id="44"> 
    <nowiki><nc:data> </nowiki>
       <nowiki><if:interfaces
xmlns:if="http://netconfcentral.org/ns/interfaces"> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>lo</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>eth0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>virbr0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
          <nowiki><if:interface> </nowiki>
             <nowiki><if:name>pan0</if:name> </nowiki>
          <nowiki></if:interface> </nowiki>
       <nowiki></if:interfaces> </nowiki>
    <nowiki></nc:data> </nowiki>
 <nowiki></nc:rpc-reply></nowiki>

=== Using Time Filters ===
The module '''yuma-time-filter.yang '''defines a timestamp mechanism to
help reduce polling overhead for a client.

* Timestamps are specified in '''date-and-time''' format (from the
'''ietf-yang-types.yang''' module).
* The timestamp parameter ''''if-modified-since'''<nowiki>' is added to
the <get> and <get-config> operations.</nowiki>
* The timestamp monitoring node ''''last-modified'''' is added to the
'''/netconf-state/datastores/datastore''' list.
* The XML attribute ''''last-modified' '''<nowiki>is added to the
<rpc-reply> element for replies to <get> and <get-config>
operations.</nowiki>
* The per-datastore last modified timestamp is for the entire datastore
contents. If the ''''if-modified-since'''<nowiki>' parameter is present
in the <get> or <get-config> request, the the server will check the
corresponding 'l</nowiki>'''ast-modified'''' timestamp.
** If the ''''last-modified'''' timestamp is more recent than the
'i'''f-modified-since'''<nowiki>' value, then the <get> or <get-config>
operation is processed as normal.</nowiki>
** If the ''''last-modified'''' timestamp is not more recent than the
'i'''f-modified-since'''<nowiki>' value, then the <get> or <get-config>
operation is not processed. </nowiki><nowiki>Instead, an empty <data>
element is returned. </nowiki><nowiki>The 'last-modified' XML attribute
in the <rpc-reply> will indicate the last modification timestamp for the
datastore.</nowiki>

Example Request:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
  <nowiki><get-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
</nowiki>
     <nowiki><source> </nowiki>
       <nowiki><running/> </nowiki>
     <nowiki></source> </nowiki>
     <nowiki><if-modified-since </nowiki>
     xmlns="[http://netconfcentral.org/ns/yuma-time-filter
http://netconfcentral.org/ns/yuma-time-filter]">
       '''2011-08-21T21:51:46Z'''<nowiki></if-modified-since> </nowiki>
   <nowiki></get-config></nowiki>
 <nowiki></rpc></nowiki>

Empty reply because datastore not modified since specified time:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><rpc-reply message-id="4" </nowiki>
    xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" 
    last-modified="'''2011-08-21T17:51:46Z'''" 
    xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> 
  <nowiki><data></data> </nowiki>
 <nowiki></rpc-reply> </nowiki>

== Notifications ==
The '''netconfd''' server supports all the capabilities of RFC 5277, and
the notification monitoring portion of the
'''ietf-netconf-monitoring.yang''' data model. There are also some
proprietary notifications defined in '''yuma-system.yang'''.

=== Subscriptions ===
<nowiki>The <create-subscription> operation is used to start receiving
notification.</nowiki>

It can be used in 4 different modes:

* Get all or some of the stored notifications.
** <nowiki><startTime> and <stopTime> parameters used; The stop time is
in the past.</nowiki>
* Get all or some of the stored notifications, then receive live
notifications until some point in the future.
** <nowiki><startTime> and <stopTime> parameters used; The stop time is
in the future.</nowiki>
* Get all or some of the stored notifications, then start receiving live
notifications until the session is terminated.
** <nowiki><startTime> parameter used, but <stopTime> parameter is not
used</nowiki>
* Start receiving live notifications until the session is terminated
** <nowiki>neither <startTime> or <startTime> are used</nowiki>

<nowiki>Once a subscription is started, notifications may start
arriving, after the <rpc-reply> for the <create-subscription> operation
is sent.</nowiki>

<nowiki>If the <startTime> parameter is used, then zero or more stored
notifications will be returned, followed by the <replayComplete>
notification.</nowiki>

<nowiki>If the <stopTime> parameter is also used, then the
<notificationComplete> notification will be sent when this stop time has
passed. </nowiki>After that, no more notifications will be sent to the
session, and the subscription is terminated. After this point, another
subscription could be started.

Only one subscription can be active on a session at a time. There is no
way to terminate a subscription, other than to close the session.

=== Notification Log ===
Each system event is saved to the notification replay buffer.

<nowiki>The <replayComplete> and <notificationComplete> notifications
are not saved to this buffer because they are subscription-specific
events, and not system events.</nowiki>

The size of the replay buffer is controlled by the '''--eventlog-size'''
configuration parameter.

The default size is 1000 events.

The oldest event will be deleted when a new event is added, when this
limit is reached.

If '''--eventlog-size '''<nowiki>is set to zero, then there will be no
replayed notifications available, and the <replayComplete> notification
will be sent right away, if <startTIme> is present.</nowiki>

Each event in the replay buffer is assigned a sequential sequence ID,
starting from 1.

<nowiki>The <sequence-id> leaf is an unsigned 32-bit integer, which is
added to the <notification> element, after the event element.
</nowiki>This sequence can be used to debug filters by comparing the
sequence IDs of the notifications that were delivered against the
expected sequence IDs.

=== Using Notification Filters ===
<nowiki>A notification filter is different than a <get> or <get-config>
filter.</nowiki>

Instead of selecting sub-trees of the specified database, it is treated
as a boolean expression. If the filter matches the content in the
notification, then the notification is sent to that subscription. If the
filter does not match the content, then the notification is not sent to
that subscription.

<nowiki>A filter match for notification purposes means that the filter
is conceptually applied, as if it were a <get> operation, and if any
nodes are selected (non-empty result node-set), then the filter is a
match. </nowiki>If no content is selected (empty result node-set), then
the filter is not a match.

The first node that can appear in the filter is the event type.
<nowiki>The <eventTime> and <sequence-id> nodes are siblings of the
event type element, so they cannot be used in a notification
filter.</nowiki>

=== <notification> Element ===
The notification element contains 2 or 3 child elements, in this order:

# '''eventTime''': timestamp for the event. The namespace URI for this
element is "urn:ietf:params:xml:ns:netconf:notification:1.0"
# '''eventType''': The real name will be the name of the YANG
notification, such as 'sysStartup'. The contents of this element will
depend on the YANG notification definition. The namespace URI for this
element will be different for every event type. It will be the same
value as the YANG namespace statement in the module that defines the
notification statement for the particular event type.
# '''sequence-id''': The system event sequence ID. Session or
subscription specific events, such as 'replayComplete' and
'notficationComplete' do not have this element. The namespace URI for
this element is "http://netconfcentral.org/ns/system".

=== <replayComplete> Event ===
<nowiki>The <replayComplete> event is generated on a subscription that
requested notification replay (by supplying the <startTime>
parameter).</nowiki>

This event type cannot be filtered out. The server will always attempt
to deliver this notification event type when it is generated.


<center>'''<nowiki><replayComplete> notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  Buffered notification delivery has ended for a subscription

|-
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  YANG file:
|  nc-notifications.yang

|}
Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification</nowiki>
      xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0"> 
    <nowiki><ncEvent:eventTime>2009-07-29T17:21:37Z</ncEvent:eventTime>
</nowiki>
    <nowiki><manageEvent:replayComplete</nowiki>
       xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/> 
 <nowiki></ncEvent:notification></nowiki>

=== <notificationComplete> Event ===
<nowiki>The <notificationComplete> event is generated on a subscription
that requested notification replay, and requested that the notification
delivery stop (i.e., terminate subscription), after a certain time,
using the <stopTime> parameter.</nowiki>

This event type cannot be filtered out. The server will always attempt
to deliver this notification event type when it is generated.


<center>'''<nowiki><notificationComplete>
notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  All notification delivery has ended, and the subscription is
terminated.

|-
|  Min parameters:
|  0

|-
|  Max parameters:
|  0

|-
|  YANG file:
|  nc-notifications.yang

|}
Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification</nowiki>
      xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0"> 
    <nowiki><ncEvent:eventTime>2009-07-29T17:31:22Z</ncEvent:eventTime>
</nowiki>
    <nowiki><manageEvent:notificationComplete</nowiki>
       xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/> 
 <nowiki></ncEvent:notification></nowiki>

=== <sysStartup> Event ===
<nowiki>The <sysStartup> event is the first notification generated when
the server starts or restarts. </nowiki><nowiki>It contains the startup
file source (if any) and lists any <rpc-error> contents that were
detected at boot-time, during the copying of the startup configuration
into the running configuration.</nowiki>


<center>'''<nowiki><sysStartup> notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  The '''netconfd''' server has started

|-
|  Min parameters:
|  0

|-
|  Max parameters:
|  2

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* '''startupSource'''
** type: string
** usage: optional (will not be present if '''--no-startup''' was
present)
** This parameter identifies the local file specification associated
with the source of the startup configuration contents.
* '''bootError'''
** <nowiki>type: list (same structure as <rpc-error> element)</nowiki>
** usage: optional (will only be present if errors were recorded during
boot)
** <nowiki>There will be one entry for each <rpc-error> encountered
during the load config operation. </nowiki><nowiki>The <rpc-error>
fields are used directly.</nowiki>
** There is no particular order, so no key is defined.
** <nowiki>All fields except <error-info> will be present from the
original <rpc-error> that was generated during the boot
process.</nowiki>

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-07-29T17:21:13Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysStartup
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:startupSource> </nowiki>
          /home/andy/swdev/yuma/trunk/netconf/data/startup-cfg.xml 
       <nowiki></sys:startupSource> </nowiki>
    <nowiki></sys:sysStartup> </nowiki>
    <nowiki><sys:sequence-id </nowiki>
       xmlns:sys="[http://netconfcentral.com/ns/system
http://netconfcentral.org/ns/system]">1
   <nowiki></sys:sequence-id> </nowiki>
 <nowiki></ncEvent:notification></nowiki>

=== <sysSessionStart> Event ===
<nowiki>The <sysSessionStart> notification is generated when a NETCONF
session is started.</nowiki>

The username, remote address, and session ID that was assigned are
returned in the event payload.


<center>'''<nowiki><sysSessionStart> notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  A new NETCONF session has started.

|-
|  Min parameters:
|  3

|-
|  Max parameters:
|  3

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* '''userName'''
** type: string
** usage: mandatory
** This parameter identifies the SSH user name that is associated with
the session.
* '''sessionId'''
** type: uint32 (range 1 to max)
** usage: mandatory
** This parameter identifies the NETCONF session ID assigned to the
session.
* '''remoteHost'''
** type: inet:ip-address
** usage: mandatory
** This parameter identifies the remote host IP address that is
associated with the session.

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-07-29T21:53:04Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysSessionStart
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:userName>andy</sys:userName> </nowiki>
       <nowiki><sys:sessionId>2</sys:sessionId> </nowiki>
       <nowiki><sys:remoteHost>192.168.0.6</sys:remoteHost> </nowiki>
    <nowiki></sys:sysSessionStart> </nowiki>
    <nowiki><sys:sequence-id</nowiki>
       xmlns:sys="[http://netconfcentral.com/ns/system
http://netconfcentral.org/ns/system]">4
    <nowiki></sys:sequence-id> </nowiki>
 <nowiki></ncEvent:notification></nowiki>

=== <sysSessionEnd> Event ===
<nowiki>The <sysSessionEnd> notification is generated when a NETCONF
session is terminated.</nowiki>

The username, remote address, and session ID that was assigned are
returned in the event payload. The termination reason is also included.

<nowiki>If the session was terminated before it properly started, it is
possible that there will not be a <sysSessionStart> notification event
to match the <sysSessionEnd> event. </nowiki><nowiki>For example, if the
initial SSH connection setup fails before the <hello> message is
processed, then only a <sysSessionEnd> notification event will be
generated. </nowiki>In this case, the user name and other session
information may not be available.


<center>'''<nowiki><sysSessionEnd> notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  A NETCONF session has terminated.

|-
|  Min parameters:
|  1

|-
|  Max parameters:
|  5

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* '''userName'''
** type: string
** usage: mandatory
** This parameter identifies the SSH user name that is associated with
the session.
* '''sessionId'''
** type: uint32 (range 1 to max)
** usage: mandatory
** This parameter identifies the NETCONF session ID assigned to the
session.
* '''remoteHost'''
** type: inet:ip-address
** usage: mandatory
** This parameter identifies the remote host IP address that is
associated with the session.
* '''killedBy'''
** type: uint32 (range 1 to max)
** usage: optional (will only be present if the terminationReason leaf
is equal to 'killed'.
** <nowiki>This parameter identifies the session number of the session
that issued the <kill-session> operation.</nowiki>
* '''terminationReason'''
** type: enumeration (closed, killed, dropped, timeout, bad-start,
bad-hello, other)
** usage: mandatory
** This parameter indicates why the session was terminated.

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-07-29T21:53:12Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysSessionEnd
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:userName>andy</sys:userName> </nowiki>
       <nowiki><sys:sessionId>2</sys:sessionId> </nowiki>
       <nowiki><sys:remoteHost>192.168.0.6</sys:remoteHost> </nowiki>
       <nowiki><sys:terminationReason>closed</sys:terminationReason>
</nowiki>
    <nowiki></sys:sysSessionEnd> </nowiki>
    <nowiki><sys:sequence-id</nowiki>
          xmlns:sys="[http://netconfcentral.com/ns/system
http://netconfcentral.org/ns/system]">5
    <nowiki></sys:sequence-id> </nowiki>
 <nowiki></ncEvent:notification></nowiki>

=== <sysConfigChange> Event ===
<nowiki>The <sysConfigChange> notification is generated when the
<running> configuration database is altered by a NETCONF
session.</nowiki>

If the ''':candidate'''<nowiki> capability is supported, then this event
is generated when the <commit> operation completes.</nowiki>

If the ''':writable-running'''<nowiki> capability is supported instead,
then this even is generated when the <edit-config> operation
completes.</nowiki>

The user name, remote address, and session ID that made the change are
reported.

A summary of the changes that were made is also included in the event
payload.

<nowiki>If multiple changes are made at once, then one <sysConfigChange>
event will be generated for each change. </nowiki>There is no
significance to the order that these events are generated.


<center>'''<nowiki><sysConfigChange> notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  <nowiki>The <running> configuration has been changed by a NETCONF
session.</nowiki>

|-
|  Min parameters:
|  4

|-
|  Max parameters:
|  4

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* '''userName'''
** type: string
** usage: mandatory
** This parameter identifies the SSH user name that is associated with
the session.
* '''sessionId'''
** type: uint32 (range 1 to max)
** usage: mandatory
** This parameter identifies the NETCONF session ID assigned to the
session.
* '''remoteHost'''
** type: inet:ip-address
** usage: mandatory
** This parameter identifies the remote host IP address that is
associated with the session.
* '''edit'''
** list (with no key) of edit operations performed, 1 entry for each
edit:
*** '''target'''
**** type: instance-identifier
**** usage: mandatory
**** This parameter contains the absolute path expression of the
database object node that was modified.
*** '''operation'''
**** type: enumeration (merge, replace, create, delete)
**** usage: mandatory
**** This parameter identifies the nc:operation that was performed on
the target node in the database.

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-07-29T22:21:18Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysConfigChange
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:userName>andy</sys:userName> </nowiki>
       <nowiki><sys:sessionId>3</sys:sessionId> </nowiki>
       <nowiki><sys:remoteHost>192.168.0.6</sys:remoteHost> </nowiki>
       <nowiki><sys:edit></nowiki>
          <nowiki><sys:target> </nowiki>
         
<nowiki>/nd:config/nacm:nacm/nacm:groups/nacm:group[nacm:groupIdentity=nacm:admin]
</nowiki>
          <nowiki></sys:target> </nowiki>
          <nowiki><sys:operation>create</sys:operation> </nowiki>
       <nowiki></sys:edit></nowiki>
    <nowiki></sys:sysConfigChange> </nowiki>
    <nowiki><sys:sequence-id</nowiki>
      
<nowiki>xmlns:sys="http://netconfcentral.org/ns/system">7</sys:sequence-id>
</nowiki>
 <nowiki></ncEvent:notification></nowiki>

=== <sysCapabilityChange> Event ===
<nowiki>The <sysCapabilityChange> notification is generated when the set
of active capabilities for the server has changed.</nowiki>

<nowiki>The most common way this notification is generated is after the
<load> operation has been used to add a new YANG module to the
system.</nowiki>

It is possible that this notification will be generated for removal of
capabilities. However, at this time, there are no NETCONF capabilities
that can be removed from the running system.

<nowiki>The <added-capability> leaf list will contain the capability URI
for each new capability that has just been added.</nowiki>

<nowiki>The <deleted-capability> leaf list will contain the capability
URI for each existing capability that has just been deleted.</nowiki>

<nowiki>The <changedBy> container will identity whether the server or a
NETCONF session caused the capability change.</nowiki>

<nowiki>If the change was made by the server, then this container will
have an empty leaf named <server>.</nowiki>

If the change was made by a NETCONF session, the user name, remote
address, and session ID for the session that caused the change are
reported.

<nowiki>If multiple changes are made at once, then one
<sysCapabilityChange> event will be generated for all the changes. There
will be multiple instances of the <added-capability> or
<deleted-capability> leaf-list elements in this case.</nowiki>

When this notification is generated, the
i'''etf-netconf-monitoring'''<nowiki> data model <capabilities> data
structure is updated to reflect the changes.</nowiki>


<center>'''<nowiki><sysCapabilityChange>
notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  <nowiki>The set of currently active <capability> URIs has
changed</nowiki>

|-
|  Min parameters:
|  2

|-
|  Max parameters:
|  5

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* choice changed-by (server or by-user)
** '''server'''
*** type: empty
*** usage: mandatory
*** If this empty leaf is present, then the server caused the capability
change.
** case by-user (if a NETCONF session caused the capability change)

* 
** 
*** '''userName'''
**** type: string
**** usage: mandatory
**** This parameter identifies the SSH user name that is associated with
the session.
*** '''sessionId'''
**** type: uint32 (range 1 to max)
**** usage: mandatory
**** This parameter identifies the NETCONF session ID assigned to the
session.
*** '''remoteHost'''
**** type: inet:ip-address
**** usage: mandatory
**** This parameter identifies the remote host IP address that is
associated with the session.
* '''added-capability'''
** type:leaf-list of capability URI strings
** usage: optional
** This parameter contains one entry for each capability that was just
added
* '''deleted-capability'''
** type:leaf-list of capability URI strings
** usage: optional
** This parameter contains one entry for each capability that was just
deleted.

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-07-29T23:03:06Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysCapabilityChange
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:changed-by> </nowiki>
          <nowiki><sys:userName>andy</sys:userName> </nowiki>
          <nowiki><sys:sessionId>3</sys:sessionId> </nowiki>
          <nowiki><sys:remoteHost>192.168.0.61</sys:remoteHost>
</nowiki>
       <nowiki></sys:changed-by> </nowiki>
       <nowiki><sys:added-capability> </nowiki>
         
http://netconfcentral.org/ns/toaster?module=toaster&amp;revision=2009-06-23&amp;features=clock

       <nowiki></sys:added-capability> </nowiki>
    <nowiki></sys:sysCapabilityChange> </nowiki>
    <nowiki><sys:sequence-id</nowiki>
       xmlns:sys="[http://netconfcentral.com/ns/system
http://netconfcentral.org/ns/system]">8
    <nowiki></sys:sequence-id> </nowiki>
 <nowiki></ncEvent:notification></nowiki>

=== <sysConfirmedCommit> Event ===
<nowiki>The <sysConfirmedCommit> notification is generated when the
state of the confirmed-commit procedure has changed.</nowiki>

<nowiki>The confirmed-commit procedure is started when a <commit>
operation with a <confirmed/> parameter is executed.</nowiki>

<nowiki>A <sysConfirmedCommit> notification is generated several times
for a single confirmed-commit procedure. </nowiki>One or more of the
following sub-events will be generated:

* '''start''': A confirmed-commit procedure has started.
** <nowiki>Sent once when the first <commit> operation is
executed.</nowiki>
** This event starts the confirmed-commit procedure.
** <nowiki>If the <candidate> database is not altered, then the
confirmed commit procedure will be skipped.</nowiki>
* '''cancel''': A confirmed-commit procedure has been canceled
** Sent only if the original session is terminated.
** This event terminates the confirmed-commit procedure.
* '''timeout''': A confirmed-commit procedure has timed out.
** Sent only if the confirm-timeout interval expires.
** This event terminates the confirmed-commit procedure.
* '''extend''': A confirmed-commit procedure has been extended.
** <nowiki>Sent if the 2nd to N-1th <confirm> operation contains a
<confirmed/> parameter.</nowiki>
** This event restarts the confirm-timeout interval, but does not reset
the backup database.
** <nowiki>Any new changes in the <candidate> database will be
committed.</nowiki>
* '''complete''': A confirmed-commit procedure has completed.
** <nowiki>Sent if the 2nd to Nth <commit> operation is executed before
the confirm-timeout interval expires.</nowiki>
** This event terminates the confirmed-commit procedure.

<center>'''<nowiki><sysConfirmedCommit>
notification</nowiki>'''</center>



{| class=wikitable border="1"
|  Description:
|  The state of the confirmed-commit procedure has changed.

|-
|  Min parameters:
|  1

|-
|  Max parameters:
|  4

|-
|  YANG file:
|  yuma-system.yang

|}
Parameters:

* '''userName'''
** type: string
** usage: mandatory
** This parameter identifies the SSH user name that is associated with
the session that caused the confirmed-commit procedure state change.
* '''sessionId'''
** type: uint32 (range 1 to max)
** usage: mandatory
** This parameter identifies the NETCONF session ID assigned to the
session.
* '''remoteHost'''
** type: inet:ip-address
** usage: mandatory
** This parameter identifies the remote host IP address that is
associated with the session.
* '''confirmEvent'''
** type: enumeration (start, cancel, timeout, extend, complete)
** usage: mandatory
** This parameter indicates why the confirmed-commit procedure changed
state.

Example:


 <nowiki><?xml version="1.0" encoding="UTF-8"?> </nowiki>
 <nowiki><ncEvent:notification
xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
</nowiki>
    <nowiki><ncEvent:eventTime>2009-08-29T23:03:06Z</ncEvent:eventTime>
</nowiki>
    <nowiki><sys:sysConfirmedCommit
xmlns:sys="http://netconfcentral.org/ns/system"> </nowiki>
       <nowiki><sys:userName>andy</sys:userName> </nowiki>
       <nowiki><sys:sessionId>3</sys:sessionId> </nowiki>
       <nowiki><sys:remoteHost>192.168.0.61</sys:remoteHost></nowiki>
       <nowiki><sys:confirmEvent>start</sys:confirmEvent></nowiki>
    <nowiki></sys:sysConfirmedCommit></nowiki>
    <nowiki><sys:sequence-id</nowiki>
       xmlns:sys="[http://netconfcentral.com/ns/system
http://netconfcentral.org/ns/system]">9
    <nowiki></sys:sequence-id> </nowiki>
 <nowiki></ncEvent:notification></nowiki>

= CLI Reference =
The '''netconfd''' program uses command line interface (CLI) parameters
to control program behavior.

The following sections document all the Yuma CLI parameters relevant to
this program, in alphabetical order.

== --audit-log ==
The '''--audit-log''' parameter specifies the file path of the
configuration edit audit log. If this parameter is present, then edits
to the running database will cause an audit log entry to be created for
each edit point. This is done in addition to normal logging, but it is
not affected by the '''–log-level''' parameter.


<center>'''--audit-log parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  ''filespec''

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --audit-log=/var/log/nc-audit.log&

|}
== --audit-log-append ==
The '''--audit-log-append''' parameter specifies that the existing audit
log file (if any) should be appended, instead of deleted. It is ignored
unless the '''--audit-log''' parameter is present.


<center>'''--audit-log-append parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --audit-log=/var/log/ncaudit.log \
   --audit-log-append&

|}
== --access-control ==
The '''--access-control''' parameter specifies how access control is
enforced in the '''netconfd''' program.

It is an enumeration with the following values:

* '''enforcing''': All configured access control rules will be enforced.
* '''permissive''': All configured access control rules will be enforced
for write and execute requests. All read requests will be allowed,
unless the requested object contains the '''nacm:very-secure'''
extension. In that case, all configured access control rules will be
enforced, and no default access will be allowed.
* '''disabled''': All read, write, and execute requests will be allowed,
unless the object contains the '''nacm:secure''' or
'''nacm:very-secure''' extension.
** If the '''nacm:secure''' extension is in effect, then all configured
access control rules will be enforced for write and execute requests.
** If the '''nacm:very-secure''' extension is in effect, then all
configured access control rules will be enforced for all requests. Use
this mode with caution.
* '''off''': All access control enforcement is disabled. Use this mode
with extreme caution.

<center>'''--access-control parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enumeration:

'''enforcing permissive disabled off'''

|-
|  Default:
|  enforcing

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --access-control=permissive

|}
== --config ==
The '''--config''' parameter specifies the name of a Yuma configuration
file that contains more parameters to process, in addition to the CLI
parameters.

Refer to the 'Configuration Files' section for details on the format of
this file.

<center>'''--config parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: complete file specification of the text file to parse for
more parameters.

|-
|  Default:
|  <nowiki>/etc/yuma/<program-name>.conf</nowiki>

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd \
   --config=~/testconf.conf

|}
== --datapath ==
The '''--datapath''' parameter specifies the directory search path to
use while searching for data files. It consists of a colon (':')
separated list of path specifications, commonly found in Unix, such as
the '''$PATH''' environment variable.

This parameter overrides the '''$YUMA_DATAPATH''' environment variable,
if it is present.

<center>'''--datapath parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: list of directory specifications

|-
|  Default:
|  '''$YUMA_DATAPATH''' environment variable

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd \
   --datapath=”~/work2:~/data”

|}
== --default-style ==
The''' --default-style''' parameter specifies the way leafs with default
values are returned from the server for data retrieval operations.
<nowiki>This setting will be used as the default behavior when
processing the operations that support the <with-defaults> extension,
and no value is provided.</nowiki>

The values and their meanings are defined in
'''ietf-with-defaults.yang'''. Here is a summary:

* '''report-all''': Report all nodes as the default behavior. The will
be the behavior used if this parameter is not specified.
* '''trim''': Report only nodes that do not have the server-assigned
value, as the default behavior. This includes all leafs with a YANG
default and any other node created by the server.
* '''explicit''': Report only nodes that have been set by client action,
as the default behavior. <nowiki>Any node created via the <startup>
configuration at boot-time is considered to be a client-created node.
</nowiki>It does not matter what the actual values are, with respect to
YANG defaults or server-supplied defaults. Any nodes created by the
server are skipped.

<center>'''--default-style parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enumeration:''' report-all trim explicit'''

|-
|  Default:
|  report-all

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --default-style=trim

|}
== --delete-empty-npcontainers ==
The '''--delete-empty-npcontainers''' parameter is a boolean that
indicates whether the server should keep or delete empty non-presence
containers in the database.

If 'true', empty NP containers will be deleted. If 'false', they will
not be deleted.


<center>'''--delete-empty-npcontainers parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean

|-
|  Default:
|  FALSE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --delete-empty-npcontainers=true

|}
== --deviation ==
The '''--deviation''' parameter is a leaf-list of modules that should be
loaded automatically when the program starts, as a deviation module. In
this mode, only the deviation statements are parsed and then made
available later when the module that contains the objects being deviated
is parsed.

The deviations must be known to the parser before the target module is
parsed.

This parameter is used to identify any modules that have deviation
statements for the set of modules being parsed (e.g., '''--module'''
and''' --subtree''' parameters).

A module can be listed with both the '''--module''' and
'''--deviation''' parameters, but that is not needed unless the module
contains external deviations. If the module only contains deviations for
objects in the same module, then the''' --deviation '''parameter does
not need to be used.

The program will attempt to load each module in deviation parsing mode,
in the order the parameters are entered.

For the '''netconfd''' program, If any modules have fatal errors then
the program will terminate.

For the '''yangdump '''and''' yangcli''' programs, each module will be
processed as requested.


<center>'''--deviation parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  module name or filespec

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  unlimited

|-
|  Supported by:
|  netconfdyangcliyangdump

|-
|  Example:
|   netconfd \
   --deviation=test1_deviations

|}
== --eventlog-size ==
The '''--eventlog-size''' parameter controls the maximum number of
events that will be stored in the notification replay buffer by the
'''netconfd''' server.

<nowiki>If set to 0, then notification replay will be disabled, meaning
that all requests for replay subscriptions will cause the
<replayComplete> event to be sent right away, since there are no stored
notifications.</nowiki>

The server will delete the oldest entry, when this limit is reached and
a new event is added to the replay buffer.

No memory is actually set aside for the notification replay buffer, so
memory limits may be reached before the maximum number of events is
actually stored, at any given time.

<center>'''--eventlog-size parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32

|-
|  Default:
|  1000

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --eventlog-size=20000

|}
== --feature-disable ==
The '''--feature-disable''' parameter directs all programs to disable a
specific feature.

This parameter is a formatted string containing a module name, followed
by a colon ':', followed by a feature name, e.g.,


     test:feature1

It is an error if a '''--feature-enable''' and '''--feature-disable'''
parameter specify the same feature.

Parameters for unknown features will be ignored.

<center>'''--feature-disable parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  formatted string (module:feature

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  unlimited

|-
|  Supported by:
|  yangcliyangdiffyangdumpnetconfd

|-
|  Example:
|   netconfd\
     --feature-disable=test:feature1

|}
== --feature-enable ==
The '''--feature-enable''' parameter directs all programs to enable a
specific feature.

This parameter is a formatted string containing a module name, followed
by a colon ':', followed by a feature name, e.g.,


     test:feature1

It is an error if a '''--feature-disable''' and '''--feature-enable'''
parameter specify the same feature.

Parameters for unknown features will be ignored.

<center>'''--feature-enable parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  formatted string (module:feature

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  unlimited

|-
|  Supported by:
|  yangcliyangdiffyangdumpnetconfd

|-
|  Example:
|   netconfd 
     --feature-enable=test:feature1

|}
== --feature-enable-default ==
The '''--feature-enable-default''' parameter controls how '''yangdump'''
will generate C code for YANG features by default.

If 'true', then by default, features will be enabled.

If 'false', then by default, features will be disabled.

If a '''--feature-enable''' or '''--feature-disable''' parameter is
present for a specific feature, then this parameter will be ignored for
that feature.


<center>'''--feature-enable-default parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean (true or false)

|-
|  Default:
|  TRUE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  yangcliyangdiffyangdumpnetconfd

|-
|  Example:
|   netconfd \
    --feature-enable-default=false

|}
== --hello-timeout ==
The''' --hello-timeout''' parameter controls the maximum number of
seconds that the '''netconfd'''<nowiki> server will wait for a <hello>
PDU, for each session.</nowiki>

<nowiki>If set to 0, then hello state timeouts will be disabled, meaning
that no sessions will be deleted while waiting for a <hello>
PDU.</nowiki>

It is strongly suggested that this parameter not be disabled, since a
denial-of-service attack will be possible if sessions are allowed to
remain in the 'hello wait' state forever. A finite number of SSH and
NETCONF sessions are supported, so if an attacker simply opened lots of
SSH connections to the netconf subsystem, the server would quickly run
out of available sessions.

<nowiki>Sessions cannot be deleted manually via <kill-session> operation
if no new sessions are being allocated by the server.</nowiki>


<center>'''--hello-timeout parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32; 0 == disabled;

range 10 .. 3600 seconds (1 hour max)

|-
|  Default:
|  600 (10 minutes)

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --hello-timeout=300

|}
== --help ==
The '''--help''' parameter causes program help text to be printed, and
then the program will exit instead of running as normal.

This parameter can be combined with the '''--help-mode''' parameter to
control the verbosity of the help text. Use '''--brief''' for less, and
'''--full '''for more than the normal verbosity.

This parameter can be combined with the '''--version''' parameter in all
programs. It can also be combined with the '''--show-errors''' parameter
in '''yangdump'''.

The program configuration parameters will be displayed in alphabetical
order, not in schema order.

<center>'''--help parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --help

|}
== --help-mode ==
The '''--help-mode''' parameter is used to control the amount of detail
printed when help text is requested in some command. It is always used
with another command, and makes no sense by itself. It is ignored unless
used with the '''--help''' parameter.


<center>'''--help-mode parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  choice of 3 empty leafs

'''--brief --normal --full'''

|-
|  Default:
|  normal

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --help --help-mode=full

|}
* '''default choice: '''normal
* '''choice help-mode'''
** '''brief'''
*** type: empty
*** This parameter specifies that brief documentation mode should be
used.
** '''normal'''
*** type: empty
*** This parameter specifies that normal documentation mode should be
used.
** '''full'''
*** type: empty
*** This parameter specifies that full documentation mode should be
used.

== --idle-timeout ==
The''' --idle-timeout''' parameter controls the maximum number of
seconds that the '''netconfd'''<nowiki> server will wait for a <rpc>
PDU, for each session.</nowiki>

<nowiki>If set to 0, then idle state timeouts will be disabled, meaning
that no sessions will be deleted while waiting for a <rpc> PDU.</nowiki>

A session will never be considered idle while a notification
subscription is active.

It is strongly suggested that this parameter not be disabled, since a
denial-of-service attack will be possible if sessions are allowed to
remain in the 'idle wait' state forever. A finite number of SSH and
NETCONF sessions are supported, so if an attacker simply opened lots of
SSH connections to the netconf subsystem, the server would quickly run
out of available sessions.

<nowiki>This parameter will affect a <confirmed-commit>
operation!</nowiki>

<nowiki>Make sure this timeout interval is larger than the value of the
<confirm-timeout> parameter used in the confirmed commit procedure.
</nowiki>Otherwise, it is possible that the session will be terminated
before the confirm-timeout interval has expired, effectively replacing
that timer with this one.


<center>'''--idle-timeout parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32; 0 == disabled;

range 30 .. 360000 seconds (100 hours max)

|-
|  Default:
|  3600 (1 hour)

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --idle-timeout=30000

|}
== --indent ==
The '''--indent''' parameter specifies the number of spaces that will be
used to add to the indentation level, each time a child node is printed
during program operation.


<center>'''--indent parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32 (0 .. 9)

|-
|  Default:
|  2

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --indent=4

|}
== --log ==
The '''--log''' parameter specifies the file name to be used for logging
program messages, instead of STDOUT. It can be used with the optional'''
--log-append''' and '''--log-level''' parameters to control how the log
file is written.


<center>'''--log parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: log file specification

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --log=~/server.log&

|}
== --log-append ==
The '''--log-append''' parameter specifies that the existing log file
(if any) should be appended , instead of deleted. It is ignored unless
the '''--log''' parameter is present.


<center>'''--log-append parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --log-append \
   --log=~/server.log&

|}
== --log-level ==
The '''--log-level''' parameter controls the verbosity level of messages
printed to the log file or STDOUT, if no log file is specified.

The log levels are incremental, meaning that each higher level includes
everything from the previous level, plus additional messages.

There are 7 settings that can be used:

* '''none''': All logging is suppressed. Use with extreme caution!
* '''error''': Error messages are printed, indicating problems that
require attention.
* '''warn''': Warning messages are printed, indicating problems that may
require attention.
* '''info''': Informational messages are printed, that indicate program
status changes.
* '''debug''': Debugging messages are printed that indicate program
activity.
* '''debug2''': Protocol debugging and trace messages are enabled.
* '''debug3''': Very verbose debugging messages are enabled. This has an
impact on resources and performance, and should be used with caution.

<center>'''log-level parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enumeration: '''off error warn info debug debug2 debug3 debug4'''

|-
|  Default:
|  --info (--debug for DEBUG builds)

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --log-level=debug \
   --log=~/server.log&

|}
== --max-burst ==
The '''--max-burst''' parameter specifies the maximum number of
notifications to send in a burst, to one session. Even though TCP will
control the transmission rate, this parameter can limit the memory usage
due to buffering of notifications waiting to be sent.

The value zero means no limit will be used at all.

<center>'''--max-burst parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32

|-
|  Default:
|  10

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcli

|-
|  Example:
|   netconfd --max-burst=100

|}
== --modpath ==
The '''--modpath''' parameter specifies the YANG module search path to
use while searching for YANG files. It consists of a colon (':')
separated list of path specifications, commonly found in Unix, such as
the '''$PATH''' environment variable.

This parameter overrides the '''$YUMA_MODPATH''' environment variable,
if it is present.


<center>'''--modpath parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: list of directory specifications

|-
|  Default:
|  '''$YUMA_MODPATH''' environment variable

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd \
   --modpath=”~/testmodules:~/modules:~/trunk/netconf/modules”

|}
== --module ==
The '''--module''' parameter is a leaf-list of modules that should be
loaded automatically when the program starts.

The program will attempt to load each module in the order the parameters
were entered.

For the '''netconfd''' program, If any modules have fatal errors then
the program will terminate.

For the '''yangdump''' program, each module will be processed as
requested.


<center>'''--module parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  module name or filespec

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  unlimited

|-
|  Supported by:
|  netconfdyangcliyangdump

|-
|  Example:
|   netconfd \
   --module=test1 \
   --module=test2

|}
== --port ==
The '''--port''' parameter specifies the TCP port number(S) that should
be used for NETCONF sessions.

This parameter specifies the TCP port numbers to accept NETCONF session
from. If any instances of this parameter are found, then the default
(port 830) will not be added automatically. Up to 4 port parameter
values can be entered.


<center>'''--port parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32

|-
|  Default:
|  830

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  4

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --port=22 \
    --port=830

|}
== --protocols ==
The '''--protocols''' parameter specifies which NETCONF protocol
versions should be enabled.The base:1.0 (RFC 4741/4742) and base:1.1
(RFC 6241/6242) capabilities are controlled with this parameter. 


<center>'''--protocols parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  bits

|-
|  Default:
|  netconf1.0 netconf1.1

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd –protocols=netconf1.0

|}
== --running-error ==
The '''--running-error''' parameter is an enumeration, specifying how
the '''netconfd''' server will treat errors encountered while validating
the running database, when loaded from the non-volatile startup
configuration at boot-time. 

* leaf '''running-error'''
** type: enumeration (stop or continue)
** Specifies if running configuration errors will be treated as fatal or
recoverable errors.

<center>'''startup-error parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enum: stop continue

|-
|  Default:
|  stop

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd  --running-error=continue

|}
== --runpath ==
The '''--runpath''' parameter specifies the server instrumentation
library (SIL) search path to use while searching for library files. It
consists of a colon (':') separated list of path specifications,
commonly found in Unix, such as the '''$PATH''' environment variable.


This parameter overrides the '''$YUMA_RUNPATH''' environment variable,
if it is present.If no path is specified or a SIL is not found, the
directories '''/usr/lib/yuma''' and '''/usr/lib64/yuma''' (for 64-bit
platforms) are checked.


<center>'''--runpath parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: list of directory specifications

|-
|  Default:
|  '''$YUMA_RUNPATH''' environment variable

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcli

|-
|  Example:
|   netconfd \
   --runpath=”~/testsil:/yuma/device”

|}
== --start ==
The '''--start''' parameter is a choice, specifying how the
'''netconfd''' server will load the non-volatile startup configuration
at boot-time. If no choice is made at all, then the server will check
its data path for the file '''startup-cfg.xml'''.

* choice '''start'''
** '''no-startup'''
*** type: empty
*** Specifies that no configuration will be loaded at all at boot-time
** '''factory-startup'''
*** type: empty
*** Force the system to use the factory configuration and delete the
startup config file if it exists. Force the NV-storage startup to
contain the factory default configuration.
** '''startup'''
*** type: string
*** Specifies the file name of the boot-time configuration. The server
expects this to be an XML configuration file. Unless a path
specification is included, the '''$YUMA_DATAPATH''' environment variable
or --datapath parameter will be used to search for the specified file
name. No '.xml' extension will be added. The exact file name will be
used instead.

<center>'''start parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  choice: '''--no-startup --factory-startup'''
'''--startup'''<nowiki>=</nowiki>''filespec''

|-
|  Default:
|  first startup-cfg.xml in the data path

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd \
   --startup=$TESTDIR/testrun

|}
== --startup-error ==
The '''--startup-error''' parameter is an enumeration, specifying how
the '''netconfd''' server will treat errors encountered while loading
the non-volatile startup configuration at boot-time. 

* leaf '''startup-error'''
** type: enumeration (stop or continue)
** Specifies if startup configuration errors will be treated as fatal or
recoverable errors.
** 

<center>'''startup-error parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enum: stop continue

|-
|  Default:
|  stop

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd  --startup-error=continue

|}
== --subdirs ==
The '''--subdirs''' parameter controls whether sub-directories should be
searched or not, if they are found during a module search.

If false, the file search paths for modules, scripts, and data files
will not include sub-directories if they exist in the specified path. 


<center>'''--subdirs parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean

|-
|  Default:
|  TRUE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  yangdump

|-
|  Example:
|   netconfd \
   --subdirs=false

|}
== --superuser ==
The '''--superuser''' parameter specifies the user name that the
'''netconfd''' server will treat as the super-user account. The 'root'
account should be used with caution. It is strongly suggested that root
access be disabled in '''sshd''', and a different account be used as the
NETCONF super-user account.

Any NETCONF session started with this user name will be exempt from
access control enforcement. <nowiki>This is especially useful if the
current yuma-nacm.yang configuration is preventing access to the <nacm>
subtree itself. </nowiki>The super-user account can be used in this
situation to repair the mis-configured access control rules.

By default, no user will be accepted as the super-user account, if no
value is specified.

To disable all super-user account privileges, set this parameter to a
zero-length string.


<center>'''--superuser parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  ''string''

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --superuser=admin

|}
== --system-sorted ==
The '''--system-sorted''' parameter specifies whether the server will
keep system-ordered lists and leaf-lists in sorted order.

If 'true', then lists and leaf-lists will be maintained in order, based
on the list keys, or leaf-list value itself. If 'false', then system
ordered entries will be kept in the order they were entered in the
database.

All entries are maintained in schema-order (except list keys are ordered
first).


<center>'''--system-sorted parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  ''boolean''

|-
|  Default:
|  TRUE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --system-sorted=false

|}
== --target ==
The '''--target''' parameter specifies the name of the database that
'''netconfd''' will use as its edit target. There are two targets
supported at this time:

* '''running'''<nowiki>: Edits will be written directly to the <running>
configuration. </nowiki>The :startup capability will also be used in
this mode. <nowiki>This means that a <copy-config> operation (from
<running> to <startup>) must be used to save any edits to non-volatile
storage, for use on the next reboot.</nowiki>
* '''candidate'''<nowiki>: Edits will be written to the <candidate>
configuration. </nowiki><nowiki>The <commit> operation must be used to
save any edits in <candidate> configuration into the <running>
configuration. </nowiki><nowiki>The non-volatile storage is updated
automatically in this mode, and the <startup> configuration will not be
present.</nowiki>

<center>'''--target parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  enumeration: '''running''' '''candidate'''

|-
|  Default:
|  candidate

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --target=running

|}
== --usexmlorder ==
The '''--usexmlorder''' parameter specifies that the '''netconfd'''
server should enforce XML ordering when applicable (such as YANG list
key leafs entered first). The default is not to check for adherence to
strict XML order, as defined by YANG.


<center>'''--usexmlorder parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  off

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --usexmlorder

|}
== --version ==
The '''--version''' parameter causes the program version string to be
printed, and then the program will exit instead of running as normal. 

All Yuma version strings use the same format:

<nowiki>DEBUG: <major>.<minor>.<svn-build-version></nowiki>

or

<nowiki>NON-DEBUG: <major>.<minor>-<release></nowiki>

An example version number that may be printed:


     netconfd 2.0-0


This parameter can be combined with the '''--help '''parameter.

<center>'''--version parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --version

|}

== --validate-config-only ==
If '''--validate-config-only''' parameter is present netconfd acts as
command line YANG configuration validator. Loads the YANG schema
modules, validates the startup configuration and exits without opening
socket and listening for incoming sessions.

This parameter can be combined with the '''--startup''' parameter
specifying the xml configuration file and '''--module''' parameter
specifying the modules (SILs or YANG modules).


{| class=wikitable border="1"
|  Syntax
|  empty

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --validate-config-only --startup-error=stop
--startup=startup-cfg-good.xml
--module=/usr/share/yuma/modules/ietf/ietf-interfaces.yang
--module=/usr/share/yuma/modules/ietf/iana-if-type.yang
|}

== --warn-idlen ==
The''' --warn-idlen''' parameter controls whether identifier length
warnings will be generated.

The value zero disables all identifier length checking. If non-zero,
then a warning will be generated if an identifier is defined which has a
length is greater than this amount.

<center>'''--warn-idlen parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32: 0 to disable, or 8 .. 1023

|-
|  Default:
|  64

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --warn-idlen=50

|}
== --warn-linelen ==
The''' --warn-linelen''' parameter controls whether line length warnings
will be generated.

The value zero disables all line length checking. If non-zero, then a
warning will be generated if a YANG file line is entered which has a
length is greater than this amount.

Tab characters are counted as 8 spaces.


<center>'''--warn-linelen parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32: 0 to disable, or 40 .. 4095

|-
|  Default:
|  72

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --warn-linelen=79

|}
== --warn-off ==
The''' --warn-off''' parameter suppresses a specific warning number.

The error and warning numbers, and the default messages, can be viewed
with the yangdump program by using the '''--show-errors''' configuration
parameter.

The specific warning message will be disabled for all modules. No
message will be printed and the warning will not count towards the total
for that module.


<center>'''--warn-off parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  uint32: 400 .. 899

|-
|  Default:
|  none

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  499

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd --warn-off=435
 <nowiki># revision order not descending</nowiki>

|}
== --with-startup ==
The''' --with-startup''' parameter controls whether the server will
support the :startup capability or not. This is a memory intensive
capability, and setting this parameter to 'false' will reduce memory
usage during normal operations. <nowiki>The non-volatile copy of the
<running> configuration will not be saved automatically if this
capability is enabled. </nowiki><nowiki>Instead, a
<copy-config>operation </nowiki><nowiki>from the <running> to <startup>
configuration will be needed.</nowiki>

<center>'''--with-startup parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean

|-
|  Default:
|  FALSE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --with-startup=true

|}
== --with-url ==
The''' --with-url''' parameter controls whether the server will support
the :url capability or not. This capability requires file system
storage.

<center>'''--with-url parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean

|-
|  Default:
|  TRUE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --with-url=false

|}
== --with-validate ==
The''' --with-validate''' parameter controls whether the server will
support the :validate capability or not. <nowiki>This is a memory
intensive capability, and setting this parameter to 'false' will reduce
memory usage during <edit-config> operations.</nowiki>

<center>'''--with-validate parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  boolean

|-
|  Default:
|  TRUE

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfd

|-
|  Example:
|   netconfd --with-validate=false

|}
== --yuma-home ==
The '''--yuma-home''' parameter specifies the project directory root to
use when searching for files.

If present, this directory location will override the ''''$YUMA_HOME'''
environment variable, if it is set. If this parameter is set to a
zero-length string, then the $'''YUMA_HOME''' environment variable will
be ignored.

The following directories are searched when either the '''$YUMA_HOME'''
environment variable or this parameter is set:

* '''$YUMA_HOME/modules'''
** This sub-tree is searched for YANG files.
* '''$YUMA_HOME/data'''
** This directory is searched for data files.
* '''$YUMA_HOME/scripts'''
** This directory is searched for '''yangcli''' script files.

<center>'''yuma-home parameter'''</center>



{| class=wikitable border="1"
|  Syntax
|  string: directory specification

|-
|  Default:
|  '''$YUMA_HOME''' environment variable

|-
|  Min Allowed:
|  0

|-
|  Max Allowed:
|  1

|-
|  Supported by:
|  netconfdyangcliyangdiffyangdump

|-
|  Example:
|   netconfd \
   --yuma-home=~/sw/netconf \
   --log=~/server.log&

|}
