Yuma netconfd Manual

YANG-Based Unified Modular Automation Tools

NETCONF Over SSH Server

Version 1.15

Last Updated: July 20, 2011

Table Of Contents

1 Preface

1.1 Legal Statements

Copyright 2009 - 2011 Andy Bierman,  All Rights Reserved.

1.2 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  Quickstart Guide

Yuma User Manual

Yuma yangcli Manual

Yuma yangdiff Manual

Yuma  yangdump Manual

Yuma Developer Manual

To obtain additional support you may join the yuma-users group on sourceforge.net and send email to this e-mail address:

yuma-users@lists.sourceforge.net

The SourceForge.net Support Page for Yuma can be found at this WEB page:

http://sourceforge.net/projects/yuma/support

There are several sources of free information and tools for use with YANG and/or NETCONF.

The following section lists the resources available at this time.

1.2.1 WEB Sites

• Netconf Central

  • http://www.netconfcentral.org/

  • Yuma Home Page

    • Free information on NETCONF and YANG, tutorials, on-line YANG module validation and documentation database

• Yuma SourceFource OpenSource Project

  • http://sourceforge.net/projects/yuma/

    • Download Yuma source and binaries; project forums and help

• Yang Central

  • 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

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

  • Free tools such as smidump, to convert SMIv2 to YANG

1.2.2 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

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

1.3  Conventions Used in this Document

The following formatting conventions are used throughout this document:

Documentation Conventions

2 netconfd User Guide

netconfd Program Components

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

2.1.1 Features

The netconfd server has the following features:

• Automatic support for all NETCONF operations, including the YANG 'insert' operation.

• Supports <candidate>, <running>, and <startup> databases

• Supports the complete NETCONF base:1.0 protocol defined in RFC 4741, and the complete NETCONF base:1.1 protocol defined in RFC 6241.

• Full, automatic run-time support for any YANG-defined NETCONF content:

  • rpc statement automatically supported, so new operations can be added at run-time

  • all YANG data statements automatically supported, so new database objects can be added at run-time

  • notification statement automatically supported, so new notification event types can be added at run-time

• Complete XML 1.0 implementation with full support for XML Namespaces

• Automatic support for all capability registration and <hello> message processing

• Full, automatic generation of all YANG module <capability> contents, including features and deviations

• Automatic session management, including unlimited number of concurrent sessions, session customization, and all database cleanup

• Full support for database locking, editing, validation, including extensive user-callback capabilities to support device instrumentation.

• Automatic support for all YANG validation mechanisms, including all XPath conditionals

• Automatic subtree and full XPath filtering

• Automatic confirmed-commit and rollback procedures

• Automatic database audit log and change notification support

• Complete <rpc-error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.

• Several <rpc-error> extensions, including <bad-value> and <error-number>, for easier debugging

• Comprehensive, fully NETCONF configurable, access control model, defined in yuma-nacm.yang.

• Complete RFC 5277 Notification support, including notification replay, :interleave capability, and several useful notifications implemented in yuma-system.yang.

• Complete RFC 5717 Partial Lock support with full XPath support, and all partial locking monitoring data defined in ietf-netconf-monitoring.yang.

• Full support for all YANG constructs, including deviations

• Full support of YANG sub-modules, including nested sub-modules

• Multiple concurrent module versions supported (import-by-revision)

• Multiple concurrent submodule versions supported (include-by-revision)

• Optimized, full XPath 1.0 implementation, including all YANG extensions

• Full implementation of the ietf-netconf-monitoring data model, including the
  <get-schema> operation to retrieve YANG modules from the server.

• Configurable default node handling, including full support of the <with-defaults> standard, in ietf-netconf-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.

2.1.2 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 setting will enable the <startup> database if set to 'true'.

• - -with-url setting will enable or disable to <url> parameter in NETCONF operations

• --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.  There is no default.  

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

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

At run-time, the <load> operation (defined in yuma-system.yang) can be used to do the same thing, except the server will simply return an <rpc-error> instead of terminate, if the requested module cannot be loaded.

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

   

netconfd --version

•  

• To get program help and exit:

   

netconfd --help

netconfd --help --brief

netconfd --help --full

•  

• To start the server in the background, set the loggin level to 'debug', and send logging messages to a log file

   

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

•  

• To start the server interactively, and send all log messages to STDOUT:

   

netconfd

•  

• To start the server interactively, with a new log file:

   

netconfd --logfile=mylogfile

•  

• To start the server interactively, and append to an existing log file:

   

netconfd -- logfile =mylogfile --log-append

•  

• To get parameters from a configuration file:

   

netconfd --config=/etc/yuma/netconfd.conf

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

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

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

Signals Recognized by netconfd

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.

2.1.7 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.  The server will attempt to find all the errors in the input <rpc> request, and not stop detecting errors after one is found.

  • All machine-readable YANG statements are utilized to automate the detection and reporting of errors.

  • A node that is present, but has a false 'when' statement, is treated as an error.

• server instrumentation PDU validation

  • Semantic requirements expressed only in description statements will be checked by device instrumentation callbacks.  The specific YANG data module should indicate which errors may be reported, and when they should be reported.

• database validation

  • Several automated tests are performed when a database is validated.

  • If the edit target is the <candidate> configuration, then referential integrity tests are postponed until the <commit> operation is attempted.

  • The specific conditions checked automatically are:

    • referential integrity condition test failed (must)

    • missing leaf (mandatory)

    • missing choice (mandatory)

    • extra container or leaf

    • too few instances of a list or leaf-list (min-elements)

    • too many instances of a list or leaf-list (max-elements)

    • instance not unique (unique)

  • Nodes that are unsupported by the server will automatically be removed from these tests.  This can occur in the following ways:

    • node is defined within a feature that is not supported (if-feature)

    • node has conditional existence test that is false (when)

    • nodes derived from a 'uses' statement which has a conditional existence test that is false (when)

    • nodes derived from an 'augment' statement which has a conditional existence test that is false (when)

• server instrumentation database validation and activation

  • Errors can occur related to the specific YANG data model module, which can only be detected and reported by the server instrumentation.

  • Resource denied errors can occur while the server instrumentation is attempting to activate the networking features associated with some configuration parameters.

  • Instrumentation code can fail for a number of reasons, such as underlying hardware failure or removal.

2.1.8 Module Summary

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

Pre-loaded YANG Modules

2.1.9 Notification Summary

The following notification event types are built into the netconfd server:

Pre-loaded Notifications

2.1.10 Operation Summary

The following protocol operations are built into the netconfd server:

Pre-loaded Operations

2.1.11 Configuration Parameter List

The following configuration parameters are used by netconfd.  Refer to the CLI Reference for more details.

netconfd CLI Parameters

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

2.2.1 :candidate

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

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

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

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

2.2.2 :confirmed-commit

The :confirmed-commit capability indicates that the server will support the <confirmed> and <confirm-timeout> parameters to the <commit> operation.

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

If the second <commit> operation is not received before the <confirm-timeout> value (default 10 minutes), then the running and candidate configurations will be reset to the contents of the running configuration, before the first <commit> operation.

If the session that started the confirmed-commit procedure is terminated for any reason before the second <commit> operation is completed, then the running configuration will be reset, as if the confirm-timeout interval had expired.

If the confirmed-commit procedure is used, and the :startup capability is also supported, then the contents of NV-storage (e.g., startup-cfg.xml) will not be updated or altered by this procedure.  Only the running configuration will be affected by the rollback,

If the <confirmed> parameter is used again, in the second <commit> operation, then the timeout interval will be extended, and any changes made to the candidate configuration will be committed.  If the running and candidate configurations are reverted, any intermediate edits made since the first <commit> operation will be lost.

2.2.3 :interleave

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

2.2.4 :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 subtree can be examined for all the YANG modules that are available for download with the <get-schema> operation.

The /netconf-state/sessions subtree can be examined for monitoring NETCONF session activity.

The /netconf-state/statistics subtree can be examined for monitoring global NETCONF counters.

2.2.5 :notification

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

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

A notification log is maintained on the server, which is restarted every time the server reboots.

This log can be accessed as a 'replay subscription'.

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

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

2.2.6 :partial-lock

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

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

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

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

The constant VAL_MAX_PLOCKS in ncx/val.h controls the maximum number of concurrent locks that a single session can own on a database node.  The default value is 4.

There is no hard resource limit for:

• the number of total partial-locks

• the number of <select> parameters in the <partial-lock> request

• the number of nodes that can be locked by a single partial-lock

When the maximum <lock-id> is reached (MAX_UINT), the server will not reset the <lock-id> to '1' unless there are no partial locks currently held on the <running> database.  The <lock-id> '0' is not used.

2.2.7 :rollback-on-error

The :rollback-on-error capability indicates that the server supports 'all-or-nothing' editing for a single <edit-config> operation. This is a standard enumeration value for the <error-option> parameter.

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

Execution phase will not occur if any errors at all are found in the validation phase.

During execution phase, this parameter will affect error processing.  When set to rollback-on-error, if any part of the requested configuration change cannot be performed, the database will be restored to its previous state, and server instrumentation callbacks to 'undo' any changes made will be invoked.

2.2.8 :schema-retrieval

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

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

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

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

The <version> parameter must be set to a revision date to retrieve a specific version of the module, or the empty string to retrieve whatever version the server is using.

2.2.9 :startup

The :startup capability indicates that the <startup> configuration is supported by the server.

By default, this capability is not supported.

This capability is controlled by the --with-startup configuration parameter.  If this parameter is set to 'true', then the :startup capability will be supported.

If this capability is supported:

• the server will allow the <startup> configuration to be the source of a <get-config>.

• the server will allow the <startup> configuration to be the target of a <copy-config> operation, if the source is the <running> configuration.

• If the :validate capability is enabled, then the server will allow the <startup> configuration to be the target of a <validate> operation.

• If the user is the super user account, or access is configured in NACM to allow it, then the server will allow the <startup> configuration to be the target of a <delete-config> operation.

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

2.2.10 :validate

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

This capability is controlled by the --with-validate configuration parameter.  If it is set to 'false' then this capability will not be available in netconfd.

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

• validate the <candidate> database if the :candidate capability is supported

• validate the <running> database

• validate the <startup> database if the :startup capability is supported

• validate an inline <config> element, which represents the entire contents of a database.

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

• set: This option is not the default, but it is probably the desired behavior for the <candidate> database.  In order to fully utilize the incremental editing capability of this database, the 'set' value should be used.  This will prevent any validation error messages unrelated to the current edit.  The <validate> operation can be used before the <commit> is done, if desired.  The same errors (if any) should be reported by <validate> or <commit>.

• test-then-set: This option is the default, and will cause a resource intensive validation procedure to be invoked every time the <candidate> database is edited.  (The validation procedure is always invoked on every edit to the <running> configuration.)  If any database validation errors are found (in addition to the requested edit), then they will be reported.  Use the <error-path> field to determine which type of error is being reported by the server.

2.2.11 :url

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

The following operations are affected by the :url capability:

• edit-config

  • <url> accepted instead of <config> as a configuration data source

• copy-config

  • <url> accepted as a source parameter.

  • <url> accepted as a target paramter.

  • <url> to <url> copy not supported (optional to implement)

• delete-config:

  • <url> accepted as source to delete

• validate

  • <url> accepted as a configuration source to validate.

Only the 'file' scheme is supported at this time.

A URL file can be specified as a simple file within the root directory.

No whitespace or special characters are allowed in the file name.

The file extension '.xml' should be used.  The server only generates and expects XML configuration files.  The NETCONF 'config' element is used as the top-level element in all <url> files.

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

Example:

<url>file:///my-backup.xml</url>

2.2.12 :with-defaults

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

• <get>

• <get-config>

• <copy-config>

There are 3 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

• trim : nodes set to thier YANG default-stmt value by the server or the client are skipped

• explicit : nodes set by the server are skipped.  (Nodes set in the <startup> are considered to be set by the client, not the server.)

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

2.2.13 :writable-running

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

All edits are activated immediately, but only if the entire database is going to be valid after the edits.  A non-destructive test is performed before activating the requested changes.

If this capability is advertised, then netconfd will also advertise the :startup capability. They are always used together.

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

2.2.14 :xpath

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

The netconfd server implements all of XPath 1.0, plus the following additions:

• the current() function from XPath 2.0 is supported

• a missing XML namespace will match any YANG module namespace (XPath 2.0 behavior) instead of matching the NULL namespace (XPath 1.0 behavior)

• the 'preceding' and 'following' axes should not be used.  The database is dynamic and the relative document order is not stable.  This is also a very resource intensive operation.

XPath filtering affects whether the server will return particular subtrees or not.  It does not change the format of the <get> or <get-config> output.  The result returned by the server will not be the raw XPath node-set from evaluating the specified 'select' expression against a database.

The server will normalize the XPath search results it returns:

• There will be no duplicate nodes, even if there were duplicates in the XPath result node-set.

• All result nodes with common ancestor nodes will be grouped together in the <rpc-reply>.

• All list nodes will include child nodes for any missing key leafs, even if they were not requested in the 'select' expression.

2.3 Databases

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

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

• <candidate>: scratch-pad to gather edits to apply to <running> all at once

• <running>: configuration data in effect

• <startup>: configuration data for the next reboot

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

The XML namespace of this element is the netconfd module namespace, but a client application should expect that other server implementations may use a different namespace, such as the NETCONF namespace,  or perhaps no namespace at all for this top-level element.

When database contents are returned in the <get>, <get-config>, or <copy-config> operations, the top-level container will be the <data> element in the NETCONF base namespace.

The top-level YANG module data structures that are present in the configuration will be present as child nodes of the <config> or <data> container node.

The exact databases that are present in the server are controlled by 3 capabilities:

• :candidate

• :writable-running

• :startup

The edit target in the server is set with the --target configuration parameter.  This will select either the :candidate or :writable-running capabilities.

The server behavior for non-volatile storage of the <running> configuration is set with the
--with-startup configuration parameter.  The :startup capability will be supported if this parameter is set to 'true'.

The following diagram shows the 4 database usage modes that netconfd supports:

2.3.1 Database Locking

It is strongly suggested that the <lock> and <unlock> operations be used whenever a database is being edited.  All the databases on the server should be locked, not just one, because different operations are controlled by different locks.  The only way to insure that the entire database transaction is done in isolation is to keep all the databases locked during the entire transaction.

The affected configurations should be locked during the entire transaction, and not released until the edits have been saved in non-volatile storage.

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

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

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

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

2.3.2 Using the <candidate> Database

The <candidate> database is available if the :candidate capability is advertised by the server.

The <lock> operation will fail on this database if there are any edits already pending in the <candidate>.  If a 'lock-failed' error occurs and no session is holding a lock, then use the <discard-changes> operation to clear the <candidate> buffer of any edits.

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

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

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

2.3.3 Using the <running> Database

The <running> database is available at all times for reading.

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

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

Once all the edits are completed, the <copy-config> operation can be used to save the current <running> configuration to non-volatile storage, by setting the target of the <copy-config> operation to the <startup> configuration.

2.3.4 Using the <startup> Database

The <startup> database is available if the :startup capability is advertised by the server.

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

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

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

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

2.4.1 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";

pattern '[a-z,A-Z][a-z,A-Z,0-9]{0,62}';

   }

}

•  

• A user name cane be 1 to 63 characters long.

• The first character must be a letter ['a' to 'z', or 'A' to 'Z']

• The remaining characters must be a letter ['a' to 'z', or 'A' to 'Z'], or a number
  ['0' to '9'].

2.4.2 Session ID

The <session-id> assigned by the server is simply a monotonically increasing number:

typedef SessionId {

   description "NETCONF Session Id";

   type uint32 {

range "1..max";

   }

}

The server will start using session ID values over again at 1, if the maximum session-id value is ever reached.

2.4.3 Server <hello> Message

The netconfd server will send a <hello> message if a valid SSH2 session to the netconf subsystem is established.

The server will list all the capabilities it supports.

The YANG module capability URI format is supported for all modules, including ones that only contain typedefs or groupings.

The URI format is defined in the YANG specification, and follows this format:

<module-namespace> '?module='<module-name>'&revision='<module-date>'

If the module does not have any revision statements, then the revision field will not be present in the module capability URI.

If the module contains any supported features, then the following field will be added, and each supported feature name will be listed:

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

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

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

Note that the deviation modules will be listed in the capabilities, along with other modules.  The 'deviations' extension allows a client tool to know that the deviations apply to the specific module, since special processing may be required.

Example server <hello> Message:

<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">

   <nc:capabilities>

      <nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:candidate:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:confirmed-commit:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:rollback-on-error:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:validate:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:xpath:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:notification:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:interleave:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:with-defaults:1.0?basic=explicit&amp;supported=report-all:trim

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:netconf-monitoring:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:schema-retrieval:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:yang:inet-types?module=ietf-inet-types&amp;revision=2009-05-13

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:netconf:monitoring?module=ietf-netconf-monitoring&amp;revision=2009-06-16

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:yang:yang-types?module=ietf-yang-types&amp;revision=2009-05-13

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-interfaces?module=interfaces&amp;rQ

ses_msg: setup send buff 1

evision=2009-07-17

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/netconfd?module=netconfd&amp;revision=2009-05-28

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&amp;revision=2008-07-14

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

      <nc:capability>

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

      </nc:capability>

   </nc:capabilities>

   <nc:session-id>1</nc:session-id>

</nc:hello>]]>]]>

2.4.4 Client <hello> Message

The netconfd server requires a valid <hello> message from the client before accepting any <rpc> requests.

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

Example client <hello> Message:

<?xml version="1.0" encoding="UTF-8"?>

<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">

   <nc:capabilities>

      <nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>

   </nc:capabilities>

</nc:hello>

2.4.5 RPC Request Processing

The only PDU the netconfd server will accept during a NETCONF session is the <rpc> message.

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

• All XML attributes in the <rpc> start tag will be returned to the client (unchanged) in the <rpc-reply> element.  The order of the XML attributes may not be preserved.

• All XML namespace prefix assignments declared in the <rpc> element (via the 'xmlns' attribute) will be used within the <rpc-reply>, and most descendant nodes of the <rpc-reply.  The exception is the <error-path> element, which may use the default XML prefix for a given module, by declaring a new xmlns attribute for the namespace.

• The so-called mandatory 'message-id' attribute is ignored by the server, along will all other XML attributes in the <rpc> element.  The server will not generate an error if this attribute is missing, as specified in RFC 4741.  The new version of the NETCONF protocol removes this rule.

All <rpc> element contents must be declared within the proper namespace, except the contents of a subtree <filter> element for a <get> or <get-config> operation.

Access control will be enforced as follows:

• All <rpc> operation requests except <close-session> will be checked in the access control model (yuma-nacm.yang).  This operation can always be invoked by any user, to allow graceful session termination in all cases.

• If the user name for the session matches the --superuser configuration parameter, then the operation will always be allowed.

• If the access control 'no-rule' default for RPC execution is set to 'permit', and there is no access control rule found to match the current <rpc> request, the the operation will always be allowed.  The default for this parameter is 'permit'.

• If a matching access control rule is found, execution access will be permitted or denied, based on the specific rule.  (I.e., 'exec' privilege bit set or not).

• If the operation reads or writes any database data, then the access control model will be checked again, for each database node specified in the request.

  • If the operation is requesting read access, then any nodes for which read permission is not granted will simply be skipped in the result.  No error or warning will be reported.

  • If the operation is requesting write access, then any nodes for which write permission is not granted will cause an 'access-denied' error.

The server does not generate inline <rpc-error> elements at this time, for any runtime exceptions that occur while retrieving data for a <get>, <get-config>, or <copy-config> operation.  Instead, unavailable nodes are just skipped.

A future version will support this feature, so managers should expect that <rpc-error> might appear within the data in a reply, not just a child node of the <rpc-reply> element.

2.4.6 Session Termination

A session can terminate for several reasons:

• <close-session> operation invoked

• <kill-session> operation invoked

• SSH session terminated unexpectedly

• TCP connection terminated unexpectedly

When a session terminates, the server does the following:

• will release any locks the session had (if any)

• will discard all changes in the <candidate> configuration, if this database was locked by the session.

• will remove the <session> list entry from the /netconf-state/sessions container

• will generate a <sysSessionEnd> notification entry for the closed or killed session

2.5 Error Reporting

All errors are reported using the standard <rpc-error> element.

If the operation does not return any data, then the <rpc-reply> element will either contain 1 <ok/> element, or 1 or more <rpc-error> elements.

If the operation returns any data (i.e., the YANG rpc definition for the operation has an 'output' section), then the <rpc-reply> element may have both <rpc-error> and data elements within it.  If there were errors in the input, then only 1 or more <rpc-error> elements will be returned.  It is possible that the required data will be returned, after any errors, but not likely.

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

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

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

2.5.1 <error-severity> Element

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

2.5.2 <error-tag> Element

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

If this field is set to 'invalid-value', then the <bad-value> element should be present in the <error-info>, identifying the invalid value that caused the problem.

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

<error-tag> Summary

2.5.3 <error-app-tag> Element

The <error-app-tag> field provided a more specific error classification than the <error-tag> field.  It is included in every <rpc-error> response.

This field is encoded as a simple string.

It is possible that error-app-tag values from different vendors will use the same string.  A client application needs to account for this shared namespace.

If the YANG 'error-app-tag' statement is defined for the specific error that occured, then it will be used instead of the default value.

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

<error-app-tag> Summary

2.5.4 <error-path> Element

The <error-path> field indicates the node that caused the error.

It is encoded as a YANG instance-identifier.

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.

<error-path>

    /nc:rpc/nc:edit-config/nc:config/nacm:nacm/nacm:groups/nacm:group

</error-path>

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

If the node that caused the error is not 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.

This extended usage of the <error-path> field is defined in the YANG specification, not the NETCONF specification.  This situation will occur if <validate> or <commit> operations detect errors.  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.

<error-path>

    /nacm:nacm/nacm:groups/nacm:group[name='admin']/groupIdentity

</error-path>

2.5.5 <error-message> Element

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

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

2.5.6 <error-info> Element

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

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

<error-info> Summary

2.5.7 instance-required Error Example

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

instance-required

Example Request:

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

   

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>none</nc:default-operation>

      <nc:config>

         <t:test2  nc:operation="create"

            xmlns:t="http://netconfcentral.org/ns/test">

            <t:foo>xxx</t:foo>

         </t:test2>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2" xmlns:t="http://netconfcentral.org/ns/test"

   xmlns:ncx="http://netconfcentral.org/ncx">

   <nc:rpc-error>

      <nc:error-type>application</nc:error-type>

      <nc:error-tag>data-missing</nc:error-tag>

      <nc:error-severity>error</nc:error-severity>

      <nc:error-app-tag>instance-required</nc:error-app-tag>

      <nc:error-path>/t:test2/t:a2</nc:error-path>

      <nc:error-message xml:lang="en">required value instance not found</nc:error-message>

      <nc:error-info>

         <ncx:error-number>310</ncx:error-number>

      </nc:error-info>

   </nc:rpc-error>

</nc:rpc-reply>

2.5.8 missing-choice Error Example

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

missing-choice error

Example Request:

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

   

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>none</nc:default-operation>

      <nc:config>

         <t:musttest  nc:operation="create"

            xmlns:t="http://netconfcentral.org/ns/test"/>

      </nc:config>

   </nc:edit-config>

</nc:rpc>]

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2" xmlns:t="http://netconfcentral.org/ns/test"

   xmlns:ncx="http://netconfcentral.org/ncx">

   <nc:rpc-error xmlns:y="urn:ietf:params:xml:ns:yang:1">

      <nc:error-type>application</nc:error-type>

      <nc:error-tag>data-missing</nc:error-tag>

      <nc:error-severity>error</nc:error-severity>

      <nc:error-app-tag>missing-choice</nc:error-app-tag>

      <nc:error-path>/t:musttest</nc:error-path>

      <nc:error-message xml:lang="en">missing mandatory choice</nc:error-message>

      <nc:error-info>

         <y:missing-choice xmlns:y="urn:ietf:params:xml:ns:yang:1">musttest</y:missing-choice>

         <ncx:error-number>296</ncx:error-number>

      </nc:error-info>

   </nc:rpc-error>

</nc:rpc-reply>

2.5.9 no-matches Error Example

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

No Matches

Example Request:

• get-schema identifier=foo version= format=yang

   

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">

      <ns:identifier>foo</ns:identifier>

      <ns:version/>

      <ns:format>ns:yang</ns:format>

   </ns:get-schema>

</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3" xmlns:ns="urn:ietf:params:xml:ns:netconf:state"

   xmlns:ncx="http://netconfcentral.org/ncx">

   <nc:rpc-error>

      <nc:error-type>protocol</nc:error-type>

      <nc:error-tag>operation-failed</nc:error-tag>

      <nc:error-severity>error</nc:error-severity>

      <nc:error-app-tag>no-matches</nc:error-app-tag>

      <nc:error-path>/nc:rpc/ns:get-schema/ns:input/ns:identifier</nc:error-path>

      <nc:error-message xml:lang="en">no matches found</nc:error-message>

      <nc:error-info>

         <ncx:bad-value>foo</ncx:bad-value>

         <ncx:error-number>365</ncx:error-number>

      </nc:error-info>

   </nc:rpc-error>

</nc:rpc-reply>

2.5.10not-in-range Error Example

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

not-in-range

Example Request:

• create /int8.1 value=1000

   

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>none</nc:default-operation>

      <nc:config>

         <t:int8.1  nc:operation="create"

            xmlns:t="http://netconfcentral.org/ns/test">1000</t:int8.1>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>none</nc:default-operation>

      <nc:config>

         <t:int8.1  nc:operation="create"

            xmlns:t="http://netconfcentral.org/ns/test">1000</t:int8.1>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

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

2.6.1 <close-session>

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

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

<close-session> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

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

Possible Operation Errors:

• none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:close-session/>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:ok/>

</nc:rpc-reply>

2.6.2 <commit>

The <commit> operation is only available when the :candidate capability is supported.

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

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.

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

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

However, if the <running> configuration encountered any errors during the initial load from NV-storage  (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.

The :confirmed-commit capability is not supported yet, so the <confirmed> and <timeout> parameters are not available at this time.

<commit> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

• <ok/>

Possible Operation Errors:

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

• in-use: the <candidate> or <running> configuration is locked by another session.

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

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="5">

   <nc:commit/>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="5">

   <nc:ok/>

</nc:rpc-reply>

2.6.3 <copy-config>

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

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

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

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.

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

• If the <target> is the <startup> configuration, then the new configuration simply overwrites the old one, and no validation is done at all.

• 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'.  All validation and access control procedures are followed.

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

<copy-config> operation

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

  • default: none

  • capabilities needed: with-defaults

  • This parameter controls how nodes containing only default values are copied to the target database.  If the <target> parameter is <candidate>, then this parameter will be ignored.

Returns:

• <ok/>

Possible Operation Errors:

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

• in-use: the configuration indicated by the <target> parameter is locked by another session.

• <commit> errors, if the target parameter is the <running> configuration

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="7">

   <nc:copy-config>

      <nc:source>

         <nc:running/>

      </nc:source>

      <nc:target>

         <nc:startup/>

      </nc:target>

   </nc:copy-config>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="7">

   <nc:ok/>

</nc:rpc-reply>

2.6.4 <create-subscription>

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

Only the 'NETCONF' stream is supported by netconfd.

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

The subscription will continue until the session is closed, unless the <stopTime> parameter is present.  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.

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.

<create-subscription> operation

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

  • type: anyxml (same as the <get> or <get-config> filter parameter)

  • default: none

  • This parameter specifies a boolean filter that should be applied to the stream.  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.

    • 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 server will prune any unauthorized payload from an eventType, but if the <eventType> itself is unauthorized, the entire notification will be dropped.

• 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.  A notification will match if its <eventTime> value is greater or equal to the value of this parameter.

• 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.  A notification will match if its <eventTime> value is less than the value of this parameter.  

    • This parameter must be greater than the startTime parameter, or an error will be returned by the server.

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

• subscription already active

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <ncEvent:create-subscription

      xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

      <ncEvent:startTime>2009-01-01T00:00:00Z</ncEvent:startTime>

   </ncEvent:create-subscription>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:ok/>

</nc:rpc-reply>

2.6.5 <delete-config>

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

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

If the :startup capability is supported, then the <startup> configuration can be cleared.  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.

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

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

<delete-config> operation

Mandatory Parameters:

• target

  • type: container with 1 of N choice of leafs

  • This parameter specifies the name of the target database for the <delete-config> operation.

  • container contents: 1 empty leaf  value supported:

    • startup

Optional Parameters:

• none

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

• in-use: <startup> database is locked

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:delete-config>

      <nc:target>

         <nc:startup/>

      </nc:target>

   </nc:delete-config>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <nc:ok/>

</nc:rpc-reply>

2.6.6 <discard-changes>

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

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

<discard-changes> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:discard-changes/>

</nc:rpc>

Example Reply:

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:ok/>

</nc:rpc-reply>

2.6.7 <edit-config>

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

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

The nc:operation 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.  This is not an error condition.

If the nc:operation attribute is used, then it may appear any number of times, and be arbitrarily nested within the <config> parameter contents.  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.

<edit-config> operation

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-se't if :validate capability is supported and 'set' otherwise

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

• in-use (target database is locked by another session)

• <commit> validation errors: if test-then-set is used or the target is the <running> configuration.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="12">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>merge</nc:default-operation>

      <nc:test-option>set</nc:test-option>

      <nc:error-option>rollback-on-error</nc:error-option>

      <nc:config>

         <t:musttest xmlns:t="http://netconfcentral.org/ns/test">

            <t:A  nc:operation="create">'testing one two'</t:A>

         </t:musttest>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="12">

   <nc:ok/>

</nc:rpc-reply>

2.6.8 <get>

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

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

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter.  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.

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

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

<get> operation

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

Returns:

• <data> element

Possible Operation Errors:

• access-denied

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:get>

      <nc:filter type="subtree">

         <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">

            <proc:cpuinfo>

               <proc:cpu>

                  <proc:cpu_MHz/>

               </proc:cpu>

            </proc:cpuinfo>

         </proc:proc>

      </nc:filter>

   </nc:get>

</nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:get>

      <nc:filter type="xpath" select="/proc/cpuinfo/cpu/cpu_MHz"/>

   </nc:get>

</nc:rpc>]

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:data>

      <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">

         <proc:cpuinfo>

            <proc:cpu>

               <proc:cpu_MHz>1600.000</proc:cpu_MHz>

               <proc:processor>0</proc:processor>

            </proc:cpu>

            <proc:cpu>

               <proc:cpu_MHz>2667.000</proc:cpu_MHz>

               <proc:processor>1</proc:processor>

            </proc:cpu>

         </proc:cpuinfo>

      </proc:proc>

   </nc:data>

</nc:rpc-reply>

2.6.9 <get-config>

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

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter.  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.

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

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

<get-config> operation

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

Returns:

• <data> element

Possible Operation Errors:

• access-denied

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:get-config>

      <nc:source>

         <nc:candidate/>

      </nc:source>

      <nc:filter type="subtree">

         <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">

            <nacm:rules>

               <nacm:moduleRule/>

            </nacm:rules>

         </nacm:nacm>

      </nc:filter>

   </nc:get-config>

</nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:get-config>

      <nc:source>

         <nc:candidate/>

      </nc:source>

      <nc:filter type="xpath" select="/nacm/rules/moduleRule"/>

   </nc:get-config>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:data>

      <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">

         <nacm:rules>

            <nacm:moduleRule>

               <nacm:moduleName>netconf</nacm:moduleName>

               <nacm:allowed-rights>read exec</nacm:allowed-rights>

               <nacm:allowed-group>nacm:guest</nacm:allowed-group>

            </nacm:moduleRule>

            <nacm:moduleRule>

               <nacm:moduleName>netconfd</nacm:moduleName>

               <nacm:allowed-rights>read write exec</nacm:allowed-rights>

               <nacm:allowed-group>nacm:admin</nacm:allowed-group>

               <nacm:comment>access to shutdown and restart rpcs</nacm:comment>

            </nacm:moduleRule>

            <nacm:moduleRule>

               <nacm:moduleName>netconf</nacm:moduleName>

               <nacm:allowed-rights>read write exec</nacm:allowed-rights>

               <nacm:allowed-group>nacm:admin</nacm:allowed-group>

               <nacm:allowed-group>nacm:monitor</nacm:allowed-group>

            </nacm:moduleRule>

         </nacm:rules>

      </nacm:nacm>

   </nc:data>

</nc:rpc-reply>

2.6.10 <get-my-session>

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

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

<get-my-session> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

• <indent>

  • type: uint32 (range 0 .. 9)

  • This parameter specifies the desired indent amount for the session.

• <linesize>

  • type: uint32 (range 40 .. 1024)

  • This parameter specifies the desired line length for the session.

• <with-defaults>

  • type: enumeration (report-all, 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:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <myses:get-my-session xmlns:myses="http://netconfcentral.org/ns/mysession"/>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="2">

   <myses:indent xmlns:myses="http://netconfcentral.org/ns/mysession">

      3

   </myses:indent>

   <myses:linesize xmlns:myses="http://netconfcentral.org/ns/mysession">

      72

   </myses:linesize>

   <myses:with-defaults xmlns:myses="http://netconfcentral.org/ns/mysession">

      report-all

   </myses:with-defaults>

</nc:rpc-reply>

2.6.11 <get-schema>

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

The 'YANG' format is supported for all YANG files loaded into the server.

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

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

<get-schema> operation

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

  • This parameter specifies the format of the module to be retrieved.  Only the YANG format is supported.

    • YANG: draft-ietf-netmod-yang

Returns:

• <data> element (contents of the YANG file)

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="55">

   <ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">

      <ns:identifier>ietf-with-defaults</ns:identifier>

      <ns:format>YANG</ns:format>

      <ns:version/>

   </ns:get-schema>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="55">

   <ns:data xmlns:ns="urn:ietf:params:xml:ns:netconf:state">

*** entire contents of YANG module would be here, no extra indenting ***

   </ns:data>

</nc:rpc-reply>

2.6.12 <kill-session>

The <kill-session> operation is used to force the termination of another NETCONF session.  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.

<kill-session> operation

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:

• <ok/>

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="42">

   <nc:kill-session>

      <nc:session-id>1</nc:session-id>

   </nc:kill-session>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="42">

   <nc:ok/>

</nc:rpc-reply>

2.6.13 <load>

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

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.

<load> operation

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:

• <mod-revision>

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

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="52">

   <nd:load xmlns:nd="http://netconfcentral.org/ns/netconfd">

      <nd:module>test2</nd:module>

   </nd:load>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="52">

   <nd:mod-revision xmlns:nd="http://netconfcentral.org/ns/netconfd">

       2008-10-15

   </nd:mod-revision>

</nc:rpc-reply>

2.6.14 <lock>

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

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

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

If the :candidate capability is supported, and it is not already locked, then it may usually be locked.  However,  the <candidate> configuration can only be locked if there are no edits already contained within it.  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.

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

<lock> operation

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:

• <ok/>

Possible Operation Errors:

• access-denied

• lock-denied (lock already held by <session-id> in the <error-info>)

• resource-denied (candidate is dirty; <discard-changes> needed)

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="62">

   <nc:lock>

      <nc:target>

         <nc:candidate/>

      </nc:target>

   </nc:lock>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="62">

   <nc:ok/>

</nc:rpc-reply>

2.6.15 <no-op>

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

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

<no-op> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="63">

   <nd:no-op xmlns:nd="http://netconfcentral.org/ns/netconfd"/>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="63">

   <nc:ok/>

</nc:rpc-reply>

2.6.16 <partial-lock>

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

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

<partial-lock> operation

Mandatory Parameters:

• <select>

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

• <lock-id>

  • type: uint32 (range 1 .. MAX_UINT)

  • This data identifies the lock ID to use when releasing the lock with the <partial-unlock> operation.

  • There will be one of these elements in the reply.

• <locked-node>

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

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="260">

   <pl:partial-lock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">

      <pl:select>//interface</pl:select>

   </pl:partial-lock>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="260" xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">

   <pl:lock-id xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">1</pl:lock-id>

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

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

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

</nc:rpc-reply>

2.6.17 <partial-unlock>

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

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

<partial-unlock> operation

Mandatory Parameters:

• <lock-id>

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

• <ok/>

Possible Operation Errors:

• access denied, invalid-value

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="263">

   <pl:partial-unlock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">

      <pl:lock-id>1</pl:lock-id>

   </pl:partial-unlock>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="263">

   <nc:ok/>

</nc:rpc-reply>

2.6.18 <restart>

The <restart> operation is used to restart the 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.

<restart> operation

Mandatory Parameters:

• none

Optional Parameters:

• none

Returns:

• none; session will be dropped upon success

Possible Operation Errors:

• access denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="63">

   <nd:restart xmlns:nd="http://netconfcentral.org/ns/netconfd"/>

</nc:rpc>

Example Reply:

[no reply will be sent; session will be dropped instead.]

2.6.19 <set-log-level>

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

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

<set-log-level> operation

Mandatory Parameters:

• <log-level>

  • type: enumeration (off, error, warn, info, debug, debug2, debug3)

  • default: none

  • This parameter specifies the server logging verbosity level.

Optional Parameters:

• none

Returns:

• <ok/>

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <myses:set-my-session xmlns:myses="http://netconfcentral.org/ns/mysession">

      <myses:indent>4</myses:indent>

      <myses:linesize>64</myses:linesize>

      <myses:with-defaults>trim</myses:with-defaults>

   </myses:set-my-session>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:ok/>

</nc:rpc-reply>

2.6.20 <set-my-session>

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

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

<set-my-session> operation

Mandatory Parameters:

• none

Optional Parameters:

• <indent>

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

• <linesize>

  • type: uint32 (range 40 .. 1024)

  • default: 72

  • This parameter specifies the desired line length for the session.

• <with-defaults>

  • type: enumeration (report-all, 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:

• <ok/>

Possible Operation Errors:

• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <myses:set-my-session xmlns:myses="http://netconfcentral.org/ns/mysession">

      <myses:indent>4</myses:indent>

      <myses:linesize>64</myses:linesize>

      <myses:with-defaults>trim</myses:with-defaults>

   </myses:set-my-session>

</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:ok/>

</nc:rpc-reply>

2.6.21 <shutdown>

The <shutdown> operation is used to shut down the netconfd server.

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