[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[NGO] netconf.yang
Hi,
I converted the NETCONF XSD to YANG as best I could.
The <get> and <get-config> attributes (type, select) are
handled with an NCX 'metadata' extension. Hopefully
we will not use XML attributes for parameters anymore.
IMO, YANG works well for describing the basic NETCONF protocol,
but the use of 'rpc' is kind of a self-referencing hack. Other
protocols than NETCONF would need language extensions, very TBD.
It would have save a lot of time if the WG was reviewing YANG
instead of ignoring the XSD (developing RFC 4741). It was painfully
difficult to get the entire XSD to match the intended structure of
the normative text, scattered throughout the document.
What if the YANG module was fully populated with the normative
documentation, instead of scattering it throughout the document?
(See many examples in the module). Perhaps protocols would be easier
to review and implement.
Andy
module netconf {
namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
prefix "nc";
// for XSD types like anyURI
import xsd { prefix "xs"; }
// for NCX 'metadata' language extension
import ncx { prefix "ncx"; }
description
"NETCONF Protocol
* Data Types
* Parmsets
* RPCs
Translated from RFC 4741.";
contact
"Translated by Andy Bierman.
Send comments to <ietf at andybierman.com>.";
revision "2008-04-16" {
description
"Initial conversion from netconf.ncx version 0.6.";
}
// NETCONF Simple Types
typedef Language {
description "XML language type for LangString";
type string {
pattern '[a-zA-Z]{1,8}(-[a-zA-Z0-9]{1,8})*';
}
}
typedef SessionId {
description "NETCONF Session Id";
type uint32 {
range "1..max";
}
}
typedef SessionIdOrZero {
description
"NETCONF Session Id or Zero to indicate none";
type uint32;
}
typedef LangString {
description "XML string with a language attribute.";
type string;
ncx:metadata "Language lang?";
}
typedef MessageId {
description "NETCONF message-id attribute";
type string {
length "1..4095";
}
}
typedef ErrorType {
description "NETCONF Error Type";
type enumeration {
enum transport;
enum rpc;
enum protocol;
enum application;
}
}
typedef ErrorTag {
description "NETCONF Error Tag";
type enumeration {
enum in-use;
enum invalid-value;
enum too-big;
enum missing-attribute;
enum bad-attribute;
enum unknown-attribute;
enum missing-element;
enum bad-element;
enum unknown-element;
enum unknown-namespace;
enum access-denied;
enum lock-denied;
enum resource-denied;
enum rollback-failed;
enum data-exists;
enum data-missing;
enum operation-not-supported;
enum operation-failed;
enum partial-operation;
}
}
typedef ErrorSeverity {
description "NETCONF Error Severity";
type enumeration {
enum error;
enum warning;
}
}
typedef TestOptionType {
description
"NETCONF 'test-option' Element Content.
This is extended with the test-only enumeration.
The 'set' option has no real effect since
the entire PDU is always validated before any
of it is applied (always test-then-set).";
type enumeration {
enum test-then-set;
enum set;
enum test-only;
}
default "set";
}
typedef ErrorOptionType {
description "NETCONF 'error-option' Element Content";
type enumeration {
enum stop-on-error;
enum continue-on-error;
enum rollback-on-error;
}
default "stop-on-error";
}
typedef FilterType {
description "NETCONF 'filter' Attribute Content";
type enumeration {
enum subtree;
enum xpath;
}
default "subtree";
}
typedef EditOperationType {
description "NETCONF 'operation' Attribute Content";
type enumeration {
enum merge;
enum replace;
enum create;
enum delete;
}
default "merge";
}
typedef DefaultOperationType {
description "NETCONF 'default-operation' Element Content";
type enumeration {
enum merge;
enum replace;
enum none;
}
default "merge";
}
typedef ConfirmTimeoutType {
description
"NETCONF 'confirm-timeout' Element Content";
type uint32 {
range "1..max";
}
units "seconds";
default "600"; // 10 minutes
}
typedef ConfigURIType {
type xs:anyURI;
}
// NETCONF Hello PDU Data Types
grouping NcCapabilities {
description "Generic Capabilities List.";
container capabilities {
config false;
leaf-list capability {
description "One Generic Capability URI.";
type xs:anyURI;
}
}
}
grouping NcAgentHello {
description "Generic Agent Hello Message Parameters.";
uses NcCapabilities;
leaf session-id {
type SessionId;
config false;
}
}
grouping NcManagerHello {
description "Generic Manager Hello Message Parameters.";
uses NcCapabilities;
}
// NETCONF Operations PDU Data Types
grouping ErrorInfoContent {
description
"NETCONF standard 'error-info' Element Content;";
leaf-list bad-attribute {
description
"Name of the missing or invalid XSD attribute.
Used with missing-attribute, bad-attribute, and
unknown-attribute error-tag values.";
type xs:QName;
config false;
}
leaf-list bad-element {
description
"Name of the element that contains (or should contain)
an invalid XSD attribute when used with missing-attribute,
bad-attribute, unknown-attribute, error-tag values.
Name of an invalid or missing element when used with
then missing-element, bad-element, unknown-element,
and unknown-namespace error-tag values.";
type xs:QName;
config false;
}
leaf-list ok-element {
description
"Identifies an element in the data model
for which the requested operation has been completed
for that node and all its child nodes. This element
can appear zero or more times in the 'error-info'
container. Used with the partial-operation error-tag
value.";
type xs:QName;
config false;
}
leaf-list err-element {
description
"Identifies an element in the data model
for which the requested operation has failed for that
node and all its child nodes. This element
can appear zero or more times in the 'error-info'
container. Used with the partial-operation error-tag
value.";
type xs:QName;
config false;
}
leaf-list noop-element {
description
"Identifies an element in the data model
for which the requested operation was not attempted for
that node and all its child nodes. This element
can appear zero or more times in the <error-info>
container. Used with the partial-operation error-tag
value.";
type xs:QName;
config false;
}
leaf session-id {
description
"Session ID of session holding the
requested lock, or zero to indicate a non-NETCONF
entity holds the lock.";
type SessionIdOrZero;
config false;
}
}
grouping RpcErrorType {
description "NETCONF 'rpc-error' Element Content";
leaf error-type {
description
"Defines the conceptual layer that the error occurred.";
type ErrorType;
mandatory true;
}
leaf error-tag {
description
"Contains a string identifying the error condition.";
type ErrorTag;
mandatory true;
}
leaf error-severity {
description
"Contains a string identifying the error severity, as
determined by the device.";
type ErrorSeverity;
mandatory true;
}
leaf error-app-tag {
description
"Contains a string identifying the data-model-specific
or implementation-specific error condition, if one exists.
This element will not be present if no appropriate
application error tag can be associated with a particular
error condition.";
type string;
}
leaf error-path {
description
"Contains the absolute XPath [2] expression identifying
the element path to the node that is associated with the error
being reported in a particular rpc-error element. This element
will not be present if no appropriate payload element can be
associated with a particular error condition, or if the
'bad-element' QString returned in the 'error-info' container is
sufficient to identify the node associated with the error. When
the XPath expression is interpreted, the set of namespace
declarations are those in scope on the rpc-error element,
including the default namespace.";
type string;
}
leaf error-message {
description
"Contains a string suitable for human display that
describes the error condition. This element will not be present
if no appropriate message is provided for a particular error
condition. This element SHOULD include an xml:lang attribute.";
type LangString;
}
anyxml error-info {
description
"Contains protocol- or data-model-specific error content.
This element will not be present if no such error content is
provided for a particular error condition. The list in
RFC 4741, Appendix A, defines any mandatory error-info content
for each error. After any protocol-mandated content, a
data model definition may mandate that certain application-layer
error information be included in the error-info container.
An implementation may include additional elements to
provide extended and/or implementation-specific debugging
information.";
}
}
grouping RpcDataReplyType {
description "NETCONF 'rpc-reply' Error and/or Data Content";
container rpc-error {
config false;
uses RpcErrorType;
}
container data {
config false;
presence "Indicates some data returned in the reply.
An empty container indicates the request produced
no response data.";
}
}
grouping RpcOkReplyType {
description "NETCONF 'rpc-reply' OK Content.";
choice ok-or-error {
leaf ok {
description
"Sent in 'rpc-reply' messages if no errors or
warnings occurred during the processing of an 'rpc' request.";
type empty;
config false;
}
container rpc-error {
uses RpcErrorType;
config false;
}
}
}
grouping RpcReplyType {
description "Generic NETCONF 'rpc-reply' content. ";
choice ok-or-data-error {
leaf ok {
description
"Sent in 'rpc-reply' messages if no errors or
warnings occurred during the processing of an 'rpc' request.";
type empty;
config false;
}
case data-error {
uses RpcDataReplyType;
}
}
}
grouping CommonConfigSourceType {
description "Common NETCONF config parameter contents.";
choice config-source {
leaf candidate {
description
"Only available if 'candidate' capability supported.";
type empty;
}
leaf running {
type empty;
}
leaf startup {
description
"Only available if 'startup' capability supported.";
type empty;
}
}
}
grouping GetConfigSourceType {
description "NETCONF config 'source' Parameter contents.";
uses CommonConfigSourceType;
augment config-source {
leaf url {
description
"URL pointing to config data. Only available
if 'url' capability supported.";
type ConfigURIType;
}
}
}
grouping RpcOperationSourceType {
description "NETCONF 'source' Parameter contents.";
uses CommonConfigSourceType;
augment config-source {
leaf url {
description
"URL pointing to config data. Only available
if 'url' capability supported.";
type ConfigURIType;
}
anyxml config {
description "Inline configuration data";
}
}
}
grouping RpcOperationTargetType {
description "NETCONF 'target' Parameter contents.";
uses CommonConfigSourceType;
augment config-source {
leaf url {
description
"URL pointing to desired config data output. Only
available if 'url' capability supported.";
type ConfigURIType;
}
}
}
// NETCONF Generic RPC Messages
container rpc {
description "Remote Procedure Call request message";
reference "RFC 4741, section 4.1";
ncx:metadata "MessageId message-id";
}
container rpc-reply {
description "Remote Procedure Call response message";
reference "RFC 4741, section 4.2";
uses RpcReplyType;
ncx:metadata "MessageId message-id";
}
// NETCONF Standard RPC Methods
rpc get-config {
description
"Retrieve all or part of a specified configuration.";
reference "RFC 4741, section 7.2";
ncx:rpc-type "monitor";
input {
container source {
description "Particular configuration to retrieve.";
// mandatory true;
uses GetConfigSourceType;
}
anyxml filter {
description "Subtree or Xpath filter to use.";
ncx:metadata "FilterType type";
ncx:metadata "string select?";
}
}
output {
anyxml config {
description
"Copy of the source database subset which matched
the filter criteria (if any).";
}
}
}
rpc edit-config {
description
"The 'edit-config' operation loads all or part of a specified
configuration to the specified target configuration. This
operation allows the new configuration to be expressed in several
ways, such as using a local file, a remote file, or inline. If
the target configuration does not exist, it will be created. If a
NETCONF peer supports the :url capability (Section 8.8), the <url>
element can appear instead of the <config> parameter and should
identify a local configuration file.
The device analyzes the source and target configurations and
performs the requested changes. The target configuration is not
necessarily replaced, as with the <copy-config> message. Instead,
the target configuration is changed in accordance with the
source's data and requested operations.";
reference "RFC 4741, section 7.2";
ncx:rpc-type "config";
input {
container target {
description "Particular configuration to edit.";
// mandatory true;
uses RpcOperationTargetType;
}
leaf default-operation {
description
"Default operation to apply if not explicitly set.";
type DefaultOperationType;
}
leaf test-option {
description
"Test option if validate capability supported.
The 'validate' capability must be present to set
this object to 'test-then-set'.";
type TestOptionType;
}
leaf error-option {
description "Error recovery option.";
type ErrorOptionType;
}
choice edit-content {
anyxml config {
description
"Inline Config content: 'config' element.";
mandatory true;
}
leaf url {
description
"Pointer to Config content: 'url' element.";
type ConfigURIType;
mandatory true;
}
}
}
}
rpc copy-config {
description
"Create or replace an entire configuration datastore with the
contents of another complete configuration datastore. If the
target datastore exists, it is overwritten. Otherwise, a new one
is created, if allowed.
If a NETCONF peer supports the :url capability (Section 8.8), the
'url' element can appear as the <source> or <target> parameter.
Even if it advertises the :writable-running capability, a device
may choose not to support the <running/> configuration datastore
as the <target> parameter of a <copy-config> operation. A device
may choose not to support remote-to-remote copy operations, where
both the <source> and <target> parameters use the <url> element.
If the source and target parameters identify the same URL or
configuration datastore, an error MUST be returned with an error-
tag containing invalid-value.";
reference "RFC 4741, section 7.3";
ncx:rpc-type "config";
input {
container target {
description "Particular configuration to copy to.";
// mandatory true;
uses RpcOperationTargetType;
}
container source {
description "Particular configuration to copy from.";
// mandatory true;
uses RpcOperationSourceType;
}
}
}
rpc delete-config {
description
"Delete a configuration datastore. The 'running' configuration
datastore cannot be deleted.
If a NETCONF peer supports the :url capability (Section 8.8), the
'url' element can appear as the <target> parameter.";
reference "RFC 4741, section 7.4";
ncx:rpc-type "config";
input {
container target {
description "Particular configuration to delete.";
uses RpcOperationTargetType;
}
}
}
rpc lock {
description
"The lock operation allows the client to lock the configuration
system of a device. Such locks are intended to be short-lived and
allow a client to make a change without fear of interaction with
other NETCONF clients, non-NETCONF clients (e.g., SNMP and command
line interface (CLI) scripts), and human users. ...";
reference "RFC 4741, section 7.5";
ncx:rpc-type "config";
input {
container target {
description "Particular configuration to lock";
// mandatory true;
uses RpcOperationTargetType;
}
}
}
rpc unlock {
description
"The unlock operation is used to release a configuration lock,
previously obtained with the 'lock' operation.
An unlock operation will not succeed if any of the following
conditions are true:
* the specified lock is not currently active
* the session issuing the <unlock> operation is not the same
session that obtained the lock
The server MUST respond with either an <ok> element or an
'rpc-error'.";
reference "RFC 4741, section 7.6";
ncx:rpc-type "config";
input {
container target {
// mandatory true;
description "Particular configuration to unlock.";
uses RpcOperationTargetType;
}
}
}
rpc get {
description
"Retrieve running configuration and device state information.";
reference "RFC 4741, section 7.7";
ncx:rpc-type "monitor";
input {
anyxml filter {
description
"This parameter specifies the portion of the system
configuration and state data to retrieve. If this parameter is
empty, all the device configuration and state information is
returned.
The filter element may optionally contain a 'type' attribute.
This attribute indicates the type of filtering syntax used
within the filter element. The default filtering mechanism in
NETCONF is referred to as subtree filtering and is described in
Section 6. The value 'subtree' explicitly identifies this type
of filtering.
If the NETCONF peer supports the :xpath capability
(Section 8.9), the value 'xpath' may be used to indicate that
the select attribute of the filter element contains an XPath
expression.";
ncx:metadata "FilterType type";
ncx:metadata "string select?";
}
}
output {
anyxml config {
description
"Copy of the 'running' database subset which matched
the filter criteria (if any).";
}
}
}
rpc close-session {
description
"Request graceful termination of a NETCONF session.
When a NETCONF server receives a <close-session> request, it will
gracefully close the session. The server will release any locks
and resources associated with the session and gracefully close any
associated connections. Any NETCONF requests received after a
'close-session' request will be ignored.";
reference "RFC 4741, section 7.8";
ncx:rpc-type "other";
}
rpc kill-session {
description
"Force the termination of a NETCONF session.
When a NETCONF entity receives a <kill-session> request for an
open session, it will abort any operations currently in process,
release any locks and resources associated with the session, and
close any associated connections.
If a NETCONF server receives a <kill-session> request while
processing a confirmed commit (Section 8.4), it must restore the
configuration to its state before the confirmed commit was issued.
Otherwise, the <kill-session> operation does not roll back
configuration or other device state modifications made by the
entity holding the lock.";
reference "RFC 4741, section 7.9";
ncx:rpc-type "exec";
input {
leaf session-id {
description "Particular session to kill.";
type SessionId;
mandatory true;
}
}
}
rpc commit {
description
"Only available if 'candidate' capability is supported.
When a candidate configuration's content is complete, the
configuration data can be committed, publishing the data set to
the rest of the device and requesting the device to conform to
the behavior described in the new configuration.
To commit the candidate configuration as the device's new
current configuration, use the <commit> operation.
The 'commit' operation instructs the device to implement the
configuration data contained in the candidate configuration.
If the device is unable to commit all of the changes in the
candidate configuration datastore, then the running
configuration MUST remain unchanged. If the device does
succeed in committing, the running configuration MUST be
updated with the contents of the candidate configuration.
If the system does not have the :candidate capability, the
'commit' operation is not available.";
reference "RFC 4741, section 8.3.4.1";
ncx:rpc-type "config";
input {
leaf confirmed {
description
"Request a confirmed commit. Only available if
'confirmed-commit' capability is supported.";
reference "RFC 4741, section 8.4.5.1";
type empty;
}
leaf confirm-timeout {
description
"Request a specific timeout period for a confirmed commit
if 'confirmed-commit' capability supported.";
reference "RFC 4741, section 8.4.5.1";
type ConfirmTimeoutType;
}
}
}
rpc discard-changes {
description
"Only available if 'candidate' capability is supported.
If the client decides that the candidate configuration should not be
committed, the 'discard-changes' operation can be used to revert the
candidate configuration to the current running configuration.
This operation discards any uncommitted changes by resetting the
candidate configuration with the content of the running
configuration.";
reference "RFC 4741, section 8.3.4.2";
ncx:rpc-type "config";
}
rpc validate {
description
"Only available if 'validate' capability is supported.
Validates the contents of the specified configuration.";
reference "RFC 4741, section 8.6.4.1";
ncx:rpc-type "config";
input {
container source {
description "Particular configuration to validate.";
// mandatory true;
uses RpcOperationSourceType;
}
}
}
}
_______________________________________________
NGO mailing list
NGO at ietf.org
https://www.ietf.org/mailman/listinfo/ngo