Subject: [netmod] 7.13.4 -- put back the <data> element

From: Andy Bierman <[email-masked]>
Date: Sun, 05 Oct 2008 13:02:19 -0700

Hi,

I think the recent change to the <rpc-reply> encoding is broken.
This change removes the <data> element and encodes the
rpc output-stmt nodes directly within <rpc-reply>, as in
the example in 7.13.5 (but not 4.2.9).

The NETCONF rpc-reply should be capable of returning
any arbitrary content to the manager, even elements <ok>
and <rpc-error>.  However, by putting the reply payload
at the same sibling level as the header nodes,
an application would very likely interpret the 'content'
as the actual header nodes they are.

Therefore, the <data> container needs to be in the PDU,
as it is defined in RFC 4741.  This ensures that no
application can possibly misinterpret the <ok> or <rpc-error>
elements within the content layer as header nodes.

Andy

_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 05 Oct 2008 22:56:43 +0200 (CEST)

Hi,

This was discussed in the email thread "rpc-reply" on the netconf list
a while back, before I made this change.  Sepcifically, we discussed
if the text in 4.2 of RFC 4741 is correct:

   The response name and response data are encoded as the contents of
   the <rpc-reply> element.  The name of the reply is an element
   directly inside the <rpc-reply> element, and any data is encoded
   inside this element.

This text specifies that the respone element is a direct child to
<rpc-reply>.

> as the actual header nodes they are.

What "header nodes"?

> elements within the content layer as header nodes.

Can you provide an example of an rpc-reply that an application can
misinterpret?  I don't understand what you mean.

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sun, 05 Oct 2008 14:24:38 -0700

> misinterpret?  I don't understand what you mean.

The elements <ok> and <rpc-error> have meaning already defined
when they are the direct child nodes of <rpc-reply>.

The NETCONF protocol is supposed to be able to carry arbitrary
content (as per the diagram everybody copies).

But without a <data> node within the <rpc-reply>,
then an application which for whatever reason
wants to return the <ok> or <rpc-error> elements
cannot do so without them being mis-interpreted.
The <data> node also future-proofs the <rpc-reply>
for any new standard-defined replies.

An RPC method called get-example-error might need
to return an <rpc-error> element, but it can't
with the data node taken out.  An application cannot
be sure if the RPC worked or not.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Sun, 05 Oct 2008 23:43:31 +0200 (CEST)

> cannot do so without them being mis-interpreted.

But other rpc's replies will be in some other namespace, so I don't
see how these replies will be mis-interpreted as <ok/> or <rpc-error>
in the netconf namespace?

> with the data node taken out.

Why not?  

For example, using the example in the draft:

  rpc activate-software-image {
      input {
          leaf image-name {
              type string;
          }
      }
      output {
          leaf status {
              type string;
          }
      }
  }

If everything is ok, the following os returned:

  <rpc-reply message-id="101"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <status xmlns="http://acme.example.com/system">
      The image acmefw-2.3 is being installed.
    </status>
  </rpc-reply>

If an error occurs, you might get:

  <rpc-reply message-id="101"
             xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <rpc-errror>
      <error-type>application</error-type>
      <error-tag>access-denied</error-tag>
      <error-severity>error</error-severity>
    </rpc-error>
  </rpc-reply>

/martin

---

From: Andy Bierman <[email-masked]>
Date: Sun, 05 Oct 2008 16:31:50 -0700

> in the netconf namespace?

So removing the <data> element is OK because
nobody is ever allowed to have a YANG module
that uses the NETCONF namespace?

That should be mentioned in the draft, not just assumed.

Removing the <data> element has another impact
on implementations that choose to generate <rpc-error>
elements inline within a reply.  This can generate
XML that is definitely invalid according to the XSD.

If the RPC output is a set of sibling nodes (e.g., a, b, c)
then if the agent generates any warnings, or if 'a'
and 'c' are not available:

      <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <rpc-error>
         <error-type>application</error-type>
         <error-tag>operation-failed</error-tag>
         <error-severity>warning</error-severity>
         <error-app-tag>data-unavailable</error-app-tag>
         <error-path>/rpc-reply/a</error-path>
       </rpc-error>
       <foo:b xmlns:a="http://example.com/ns/foo">foo-bar</foo:b>
       <rpc-error>
         <error-type>application</error-type>
         <error-tag>operation-failed</error-tag>
         <error-severity>warning</error-severity>
         <error-app-tag>data-unavailable</error-app-tag>
         <error-path>/rpc-reply/c</error-path>
       </rpc-error>
     </rpc-reply>

The XSD for <rpc-reply> specifies the <rpc-error> element,
and including it again after the <b> element in a PDU will likely
cause a parser to complain.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 06 Oct 2008 09:32:41 +0200 (CEST)

> That should be mentioned in the draft, not just assumed.

It is stated that all XML elements are in the module's namespace.

> elements inline within a reply.

I though we said earlier that inline rpc-error was not rfc 4741
compliant?  If it is complient, what are the rules for such inline
errors?  Are these rules data modelling language specific?

/martin

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Oct 2008 01:59:43 -0700

>> That should be mentioned in the draft, not just assumed.

The draft mentions that the namespace URI defined by RFC 4741
is reserved and can not ever be used in a YANG module?

> errors?  Are these rules data modelling language specific?

Within the <data> element they are inline.
As child nodes of <rpc-reply> they are not.

Andy

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 06 Oct 2008 13:13:00 +0200 (CEST)

> is reserved and can not ever be used in a YANG module?

No of course not.  It would be very useful if we had a netconf.yang
module published.  The <get> operation could be something like:

  rpc get {
   input {
     anyxml filter;
   }
   output {
     anyxml data;
   }
 }

/martin

---

From: Ladislav Lhotka <[email-masked]>
Date: Mon, 06 Oct 2008 13:23:43 +0200

> No of course not.  It would be very useful if we had a netconf.yang

But can it be done? For one, YANG cannot model XML attributes.

Lada

-- 
Ladislav Lhotka, CESNET
PGP Key ID: E74E8C0C

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Oct 2008 07:38:26 -0700

> module published.  The <get> operation could be something like:

What about the <ok> element?
What about the <rpc-error> element?
If any RPC method in the fictitious netconf.yang module
had a node named 'ok' or 'rpc-error' in the output section,
then the missing <data> element becomes a problem.
Any future common child nodes of <rpc-reply> would
also be problematic.

I prefer the YANG mapping to NETCONF to be 100% deterministic,
such that any possible QName could be used in the NETCONF content
layer.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Oct 2008 07:40:17 -0700

> errors?  Are these rules data modelling language specific?
Turning this around for a second...

What problem is solved by removing the <data> element?
It saves 13 bytes on the wire?  Big deal?  In XML terms,
that's one drop in the bucket.

Andy

---

From: Balazs Lengyel <[email-masked]>
Date: Mon, 06 Oct 2008 17:08:01 +0200

Hello,
When we send the rpc-reply
- Can we send back both an rfc4741 error and the output parameters?
IMHO yes, as this is needed for partial errors
- Can we send back both an rfc4741 OK and the output parameters?
IMHO this should be specified, but I don't care, maybe no.

Or if there is anything defined in for the rpc output, then rfc4741 OK or the rfc4741 standard 
errors are unusable?

Actually I like Andy's idea, using the <data> node answers all these questions. All output 
parameters would be encoded inside the data element.

Balazs

-- 
Balazs Lengyel                       Ericsson Hungary Ltd.
TSP System Manager
ECN: 831 7320                        Fax: +36 1 4377792
Tel: +36-1-437-7320     email: [email-masked]
_______________________________________________
netmod mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netmod

---

From: Andy Bierman <[email-masked]>
Date: Mon, 06 Oct 2008 09:25:01 -0700

> But can it be done? For one, YANG cannot model XML attributes.

I use an extension called 'metadata' for that.
At first I hated the extension-stmt, now I think it's
one of the best parts of YANG.

I use the attached netconf.yang file in my data-driven
tools.  (Warning: may not be 100% debugged yet.
It won't compile without the other modules too.)

I want to be able to use the same 'rpc-reply' container
for every RPC message, and not generate a 'foo-rpc-reply'
container for every RPC method.  The stable anyxml 'data'
node is very useful for handling the RPC reply in a centralized
dispatcher.

I think the NETCONF WG got it right by clearing identifying
the content payload in the <rpc-reply>.  I no longer agree
with the recent interpretation that the <data> node in the XSD
just applies to the RPC methods in RFC 4741.  The WG clearly
intended to create an XSD that applies to all RPCs.

In order to represent the new rpc-reply in YANG, you would
have the useless construct:

    anyxml rpc-reply {
        config false;
    }

Andy

>> module published.  The <get> operation could be something like:

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
        * Abstract object for PDU components
        * RPCs
       Translated from RFC 4741.";

   contact
     "Translated by Andy Bierman.
      Send comments to <[email-masked]>.";

   revision "2008-08-30" {
     description 
       "Add some NCX extensions to automate some agent processing.";
   }

   revision "2008-04-26" {
     description 
       "Change get-config and get output from 'config' to 'data'.";
   }

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

   container agent-hello {
     description "Generic Agent Hello Message Parameters.";

     uses NcCapabilities;

     leaf session-id {
        type SessionId;
        config false;
     }

     ncx:hidden;
     ncx:abstract;
   }

   container mgr-hello {

     description "Generic Manager Hello Message Parameters.";

     uses NcCapabilities;

     ncx:hidden;
     ncx:abstract;
   }

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

      list rpc-error {
        config false;
        uses RpcErrorType;
      }
      anyxml data {
        config false;
      }
   }

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

        list rpc-error {
          config false;
          uses RpcErrorType;
        }
      }
   }

   grouping RpcReplyType {
      description "Generic NETCONF 'rpc-reply' content. ";

      choice ok-or-data-error {
        mandatory true;
        config false;

        leaf ok {
          description
            "Sent in 'rpc-reply' messages if no errors or
             warnings occurred during the processing of an 'rpc' request.";
          type empty;
        }

        case data-error {
           uses RpcDataReplyType;
        }
      }
   }

   grouping CommonConfigSourceType {
      description "Common NETCONF config parameter contents.";

      choice config-source {
        mandatory true;

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

        container config {
          description "Inline configuration data";
	  ncx:root;
        }
      }
   }

   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 operation attribute
   leaf operation {
     description 
       "Internal object for the nc:operation attribute.";
     type EditOperationType;
     ncx:abstract;
     ncx:hidden;
   }

   // NETCONF Generic RPC Messages

   container rpc {
     description "Remote Procedure Call request message";
   
     reference "RFC 4741, section 4.1";

     // do not treat missing message-id as an error
     ncx:metadata  "MessageId message-id";
     ncx:abstract;
   }

   container rpc-reply {
     description "Remote Procedure Call response message";

     reference "RFC 4741, section 4.2";

     uses RpcReplyType;

     // do not treat missing message-id as an error
     ncx:metadata  "MessageId message-id";
     ncx:abstract;
   }

   // 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.";
          uses GetConfigSourceType;
        }

        anyxml filter {
          description "Subtree or Xpath filter to use.";
          ncx:metadata "FilterType type";
          ncx:metadata "string select";
        }
      }

      output {
        anyxml data {
          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 {
          mandatory true;
          container config {
            description 
              "Inline Config content: 'config' element.";
            ncx:root;
          }
          leaf url {
            description 
              "Pointer to Config content: 'url' element.";
            type ConfigURIType;
          }
        }
      }
   }

   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 data {
          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;
        }
      }
   }

   container config {
     description 
       "Used as the container for NETCONF object definitions.";
     ncx:root;
     ncx:abstract;
   }
        
}

---

From: Phil Shafer <[email-masked]>
Date: Mon, 06 Oct 2008 12:22:55 -0400

>that's one drop in the bucket.

Turning it around again (and trimming the quoted noise)....

What problem is solved by having the <data> element?

Thanks,
 Phil

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 06 Oct 2008 18:46:06 +0200 (CEST)

> that's one drop in the bucket.

Personally I can live with either solution.  My original
interpretation of 4741 was that <data> had to be there, so that's what
I have in my code... But then I re-read section 4.2 which says:

   the <rpc-reply> element.

... and I asked the question to the list if the text or XSD is
correct.  Usually in these cases the text is right and the XSD wrong.

/martin

---

From: Phil Shafer <[email-masked]>
Date: Mon, 06 Oct 2008 13:48:57 -0400

Martin Bjorklund writes:
>Usually in these cases the text is right and the XSD wrong.

Amen.

Thanks,
 Phil

---

From: "tom.petch" <[email-masked]>
Date: Fri, 10 Oct 2008 11:27:23 +0200

I agree with Andy on this.

Back on 21st August, on the Netconf list, Bert asked for text on what I take to
be this issue to discuss and I do not recall seeing this text or the discussion.

If 7.13.4 is this text, then I am against it.

And should this discussion be on the Netconf list instead or as well?

Tom Petch

----- Original Message -----
From: "Andy Bierman" <[email-masked]>
To: "Ladislav Lhotka" <[email-masked]>
Cc: <[email-masked]>
Sent: Monday, October 06, 2008 6:25 PM
Subject: Re: [netmod] 7.13.4 -- put back the <data> element

> >> module published.  The <get> operation could be something like:

--------------------------------------------------------------------------------

>        "Used as the container for NETCONF object definitions.";

--------------------------------------------------------------------------------