Subject: Re: [netconf] Capability-fetching mechanisms

From: "maqiufang (A)" <[email-masked]>
Date: Thu, 1 Jul 2021 13:41:39 +0000

Hi, Mahesh:
    Please see my reply inline.
From: Mahesh Jethanandani [mailto:[email-masked]]
Sent: Tuesday, June 29, 2021 6:41 AM
To: Qin Wu <[email-masked]>
Cc: Kent Watsen <[email-masked]>; maqiufang (A) <[email-masked]>; Zmail <[email-masked]>; [email-masked]
Subject: Re: [netconf] Capability-fetching mechanisms

Hi Qin,

Thank you for sharing an example. We now understand better what was intended. After discussing some, three things come to mind.

1)      We do not have a particular requirement for an off-line format, and find it an unnecessary overhead of having to wrap the data with yang-instance-data.
[Qiufang Ma] We understand that http-notif has no requirement for an off-line format, but why reject an extra mechanism to get the receiver capabilities without a need for a live receiver side?
YANG-instance-file is made up of a header part and content-data. The header part carries metadata most of which are optional, and the content data carries our necessary capabilities.

2)      There seems to be an implication of the receiver being a NETCONF server, something that we made an effort to avoid in the first place.
[Qiufang Ma] The capabilities of the receiver side can be documented in offline yang-instance-file so that the publisher can access the files in any accessible way. There is no additional requirement that the receiver side be the NETCONF or RESTCONF server. We do not even require that the receiver side be the HTTP server. Hopefully this clarifies.

3)      The data export capabilities other leafs that we do not care about. How do we restrict the response to data that is pertinent to our transport draft? In the example you shared, we see capabilities for udp-notif being returned in addition to http-notif.
[Qiufang Ma] Our mechanism is to discover the full capabilities of the publisher/receiver side, not just http-notif-related. I understand that http-notif does not care about other transport capabilities, I think udp-notif is the same. Repeated capability queries for each individual transport protocol seem inflexible and incur unnecessary overhead.

Best Regards,
Qiufang Ma

For these reasons, we feel the that the value proposition is limited, while increasing complexity.

Mahesh & Kent

On Jun 15, 2021, at 5:27 AM, Qin Wu <[email-masked]<mailto:[email-masked]>> wrote:

[Qin Wu] Here is the example:
   The publisher can send the following request to learn the receiver
   capabilities.

   GET HTTP 1.1 /some/path/capabilities/acme-receiver-capabilities.json
   Host: example.com<http://example.com/>
   Accept: application/xml, application/json

   If the receiver is unable to reply using "application/xml",

the response might look like this:

   HTTP/1.1 200 OK

   Date: Wed, 26 Feb 2020 20:33:30 GMT

   Server: example-server

   Cache-Control: no-cache

   Content-Type: application/json

   Content-Length: nnn

   {

     "ietf-yang-instance-data:instance-data-set": {

       "name": "acme-receiver-capabilities",

       "content-schema": {

         "module": "ietf-data-export-capabilities"

       },

       "timestamp": "2018-01-25T17:00:38Z",

       "description": [

         "Receiver capability"

       ],

       "content-data": {

         "system-capabilities": {

           "ietf-data-export-capabilities:data-export-capabilities": [

             {

               "transport-protocol": "http-notif",

               "encoding-format": [

                 "json",

                 "xml",

                 "rfc8639-enabled"

               ]

             },

             {

               "transport-protocol": "udp-notif",

               "encoding-format": [

                 "binary"

               ]

             }

           ]

         }

       }

     }

}

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Mon, 19 Jul 2021 14:29:51 +0000

Hi,

I think that it would be good if we could somehow get to a conclusion on this thread, so that we are able to progress draft-ietf-netconf-https-notif.

(1) My first question is whether we definitely need a dynamic mechanism to discover an HTTPS receiver’s capabilities?

I would have thought that in most cases, the management entity configuring the subscription would also know what format the receiver is able to handle those notifications.  Given that there are two solutions on how to handle to share this dynamic receiver encoding parameters, I assume that there is a demand and use case for this, but I can also see an argument that any such mechanism should be optional to implement and the mechanism being lightweight seems like a benefit.

(2) Regarding the capability mechanism in draft-ietf-netconf-https-notif:
This mechanism looks pretty lightweight to me.  I did have a couple of questions though.

(i)                  Did you consider using rfc8791 to define the receiver-capabilities?  This could allow it to be put into a YANG module, which could also easily allow the information to be made available a YANG instance data document, allowing it to be used for offline purposes.

(ii)                I wasn’t sure why you used inet:uri’s for the capabilities rather than YANG identities.  I guess that this would be a bit more work because it would require both an IANA maintained registry of capabilities and also a derived IANA registry of YANG identities that would be automatically updated by IANA whenever a new capability is added to the registry.  E.g., following the approach for say for iana-routing-types YANG Module<https://www.iana.org/assignments/iana-routing-types/iana-routing-types.xhtml>

(3) After reading draft-tao-netconf-data-export-capabilities and this thread, I’m still somewhat struggling to understand exactly where/how the YANG module that this draft defines would be used:

(i) I can see how it can be used to provide additional information about what capabilities a server (i.e., publisher) supports, and it leverages draft-ietf-netconf-notification-capabilities.  I can see how it can be used to export server capabilities to a management client either via regular NETCONF/RESTCONF requests or as an offline YANG instance data file.  However, this is not documenting the capabilities that the receiver can handle, but instead is only documenting what encodings a server is capable of encoding the notifications in.

(ii) But Qin’s example suggests that the same YANG module could be used by a receiver to advertise the receiver capabilities encoded as a YANG instance data document.  Making the receive capabilities available in an offline format is potentially helpful but using the same instance data format during a dynamic exchange seems a bit more complex, and if it was receiving the full capabilities from a receiver (e.g., if the receiver was a NETCONF/RESTCONF server) then this could end up being a much larger file compared with the approach proposed in draft-ietf-netconf-https-notif.

(4) There is a question about whether these capabilities should be defined on a per transport basis, or generically, agnostic to the transport mechanism.  My instincts here are that not all capabilities will necessarily be supported by all transports, nor do I think that there will either be that many transports nor that many capabilities.  This would seem to suggest that defining these on a per transport basis probably isn’t likely to be a problem.

Trying to close this issue during the NETCONF session (or even over email beforehand) would be great.

Regards,
Rob

From: netconf <[email-masked]> On Behalf Of maqiufang (A)
Sent: 01 July 2021 14:42
To: Mahesh Jethanandani <[email-masked]>; Qin Wu <[email-masked]>
Cc: [email-masked]
Subject: Re: [netconf] Capability-fetching mechanisms

Hi, Mahesh:
    Please see my reply inline.
From: Mahesh Jethanandani [mailto:[email-masked]]
Sent: Tuesday, June 29, 2021 6:41 AM
To: Qin Wu <[email-masked]<mailto:[email-masked]>>
Cc: Kent Watsen <[email-masked]<mailto:[email-masked]>>; maqiufang (A) <[email-masked]<mailto:[email-masked]>>; Zmail <[email-masked]<mailto:[email-masked]>>; [email-masked]<mailto:[email-masked]>
Subject: Re: [netconf] Capability-fetching mechanisms

Hi Qin,

  1.  We do not have a particular requirement for an off-line format, and find it an unnecessary overhead of having to wrap the data with yang-instance-data.
[Qiufang Ma] We understand that http-notif has no requirement for an off-line format, but why reject an extra mechanism to get the receiver capabilities without a need for a live receiver side?
YANG-instance-file is made up of a header part and content-data. The header part carries metadata most of which are optional, and the content data carries our necessary capabilities.

  1.  There seems to be an implication of the receiver being a NETCONF server, something that we made an effort to avoid in the first place.
[Qiufang Ma] The capabilities of the receiver side can be documented in offline yang-instance-file so that the publisher can access the files in any accessible way. There is no additional requirement that the receiver side be the NETCONF or RESTCONF server. We do not even require that the receiver side be the HTTP server. Hopefully this clarifies.

  1.  The data export capabilities other leafs that we do not care about. How do we restrict the response to data that is pertinent to our transport draft? In the example you shared, we see capabilities for udp-notif being returned in addition to http-notif.
[Qiufang Ma] Our mechanism is to discover the full capabilities of the publisher/receiver side, not just http-notif-related. I understand that http-notif does not care about other transport capabilities, I think udp-notif is the same. Repeated capability queries for each individual transport protocol seem inflexible and incur unnecessary overhead.

Best Regards,
Qiufang Ma

Mahesh & Kent

   HTTP/1.1 200 OK

   Server: example-server

   Cache-Control: no-cache

   Content-Length: nnn

   {

       "content-schema": {

       },

       "description": [

         "Receiver capability"

       ],

       "content-data": {

         "system-capabilities": {

             {

               "encoding-format": [

                 "json",

                 "xml",

                 "rfc8639-enabled"

               ]

             },

             {

               "encoding-format": [

                 "binary"

               ]

             }

           ]

         }

       }

     }

}

---

From: "maqiufang (A)" <[email-masked]>
Date: Tue, 20 Jul 2021 10:15:50 +0000

Hi, Rob,

Please see my reply inline.
From: Rob Wilton (rwilton) [mailto:[email-masked]]
Sent: Monday, July 19, 2021 10:30 PM
To: maqiufang (A) <[email-masked]>; Mahesh Jethanandani <[email-masked]>; Qin Wu <[email-masked]>; Kent Watsen <[email-masked]>
Cc: [email-masked]
Subject: RE: [netconf] Capability-fetching mechanisms

Hi,

(i)                  I can see how it can be used to provide additional information about what capabilities a server (i.e., publisher) supports, and it leverages draft-ietf-netconf-notification-capabilities.  I can see how it can be used to export server capabilities to a management client either via regular NETCONF/RESTCONF requests or as an offline YANG instance data file.  However, this is not documenting the capabilities that the receiver can handle, but instead is only documenting what encodings a server is capable of encoding the notifications in.
[Qiufang Ma] As you said, we originally focus on exposing server capabilities to a management client via NETCONF/RESTCONF message exchange. We also investigate how server capabilities can be advertised using offline yang instance data file and how client capability can be learnt using offline yang instance data file. Based on our analysis, it looks the client capability discovery lacks a good use case. Therefore we decide to focus only on server capability discovery in draft-tao-netconf-data-export-capabilities. If https-notif does have a requirement for discovering the capabilities that the receiver can handle, we leave it to https-notif draft to define.

(ii)                But Qin’s example suggests that the same YANG module could be used by a receiver to advertise the receiver capabilities encoded as a YANG instance data document.  Making the receive capabilities available in an offline format is potentially helpful but using the same instance data format during a dynamic exchange seems a bit more complex, and if it was receiving the full capabilities from a receiver (e.g., if the receiver was a NETCONF/RESTCONF server) then this could end up being a much larger file compared with the approach proposed in draft-ietf-netconf-https-notif.
[Qiufang Ma] As we clarified above, we think draft-tao-netconf-data-export-capabilities focuses on server capability fetching rather than client capability fetching.
Therefore we believe https-notif looks into different use case. But for UDP-notif and other potential transport protocols, they can use NETCONF/RESTCONF protocol fetch transport related capabilities.
Comparing client capability fetching mechanism in the https-notif with server capability fetching defined in draft-tao-netconf-data-export-capabilities doesn't make sense, agreed?

(4) There is a question about whether these capabilities should be defined on a per transport basis, or generically, agnostic to the transport mechanism.  My instincts here are that not all capabilities will necessarily be supported by all transports, nor do I think that there will either be that many transports nor that many capabilities.  This would seem to suggest that defining these on a per transport basis probably isn’t likely to be a problem.
[Qiufang Ma] Based on capability fetching discussion on this thread, we believe the agreement is we should focus on a common data model rather than common protocol.
In addition, all capabilities are optional attributes, for some capabilities, we define it as empty type, therefore you don't need to specify all capabilities for each transport.
if https-notif doesn't require any server capabilities to be fetched, that is fine. The model proposed in this draft works for other server capabilities advertisement cases, e.g., UDP-Notif, YANG Notifications defined in RFC8639, RFC8641.
Hopefully this clarifies.☺

Best Regards,
Qiufang Ma

Regards,
Rob

From: netconf <[email-masked]<mailto:[email-masked]>> On Behalf Of maqiufang (A)
Sent: 01 July 2021 14:42
To: Mahesh Jethanandani <[email-masked]<mailto:[email-masked]>>; Qin Wu <[email-masked]<mailto:[email-masked]>>
Cc: [email-masked]<mailto:[email-masked]>
Subject: Re: [netconf] Capability-fetching mechanisms

Hi, Mahesh:

Hi Qin,

Best Regards,
Qiufang Ma

Mahesh & Kent

   HTTP/1.1 200 OK

   Server: example-server

   Cache-Control: no-cache

   Content-Length: nnn

   {

       "content-schema": {

       },

       "description": [

         "Receiver capability"

       ],

       "content-data": {

         "system-capabilities": {

             {

               "encoding-format": [

                 "json",

                 "xml",

                 "rfc8639-enabled"

               ]

             },

             {

               "encoding-format": [

                 "binary"

               ]

             }

           ]

         }

       }

     }

}

---

From: Kent Watsen <[email-masked]>
Date: Tue, 20 Jul 2021 16:31:44 +0000

Hi Rob and Qiufang,

> On Jul 20, 2021, at 6:15 AM, maqiufang (A) <[email-masked]> wrote:
> 
> Hi, Rob,
>  

The issue goes back to RFC 8639 (Subscription to YANG Notifications) where the “encoding” leaf is left optional in case other solutions exist.   Having the inband negotiation is mostly for deployment flexibility.

> (i)                  Did you consider using rfc8791 to define the receiver-capabilities?  This could allow it to be put into a YANG module, which could also easily allow the information to be made…

No, we didn’t consider using an sx:structure, but that would be okay (IMO) as it doesn’t imply at all that the Receiver is a “server”.   Good suggestion.  That said, I’m unsure how an sx:structure would appear in a "YANG instance data document”, or any configuration or state data tree for that matter.

> (ii)                I wasn’t sure why you used inet:uri’s for the capabilities rather than YANG identities.  I guess that this would be a bit more work because it would require both an IANA maintained registry of capabilities and also a derived IANA registry of YANG identities that would be automatically updated by IANA whenever a new capability is added to the registry.  E.g., following the approach for say for iana-routing-types YANG Module <https://www.iana.org/assignments/iana-routing-types/iana-routing-types.xhtml>
I’m unsure if the use of identities was ever discussed.  It seems reasonable and, if not mistaken, would NOT require an IANA registry of any sort…as the identities (on the wire) would be scoped by their modules.   The only “downside” is the “overhead” introduce for custom (non-standard) capabilities, but it doesn’t seem meaningful relative to getting IANA out of having to maintain a registry of any kind.

> Hopefully this clarifies.J

Reading all of Rob’s and Qiufang’s comments above, it seems that we’ve gotten the point where the scales are tipping towards https-notif NOT using the "YANG instance data document” structure to encode a “system-capabilities” node having "data-export-capabilities” augmentations.  Yes?

Thank you Qiufang for taking the time help us understand the proposal fully.  I think that it is fair to say that we understand that the “opportunity” exists, but the extra complexity seems unnecessary for the very limited use-case in mind here.

Kent // contributor

---

From: Pierre Francois <[email-masked]>
Date: Thu, 22 Jul 2021 13:43:36 +0200

Kent,

(ii)                I wasn’t sure why you used inet:uri’s for the
> capabilities rather than YANG identities.  I guess that this would be a bit
> more work because it would require both an IANA maintained registry of
> capabilities and also a derived IANA registry of YANG identities that would
> be automatically updated by IANA whenever a new capability is added to the
> registry.  E.g., following the approach for say for iana-routing-types
> YANG Module
> <https://www.iana.org/assignments/iana-routing-types/iana-routing-types.xhtml>
>
>
> I’m unsure if the use of identities was ever discussed.  It seems
> reasonable and, if not mistaken, would NOT require an IANA registry of any
> sort…as the identities (on the wire) would be scoped by their modules.
> The only “downside” is the “overhead” introduce for custom (non-standard)
> capabilities, but it doesn’t seem meaningful relative to getting IANA out
> of having to maintain a registry of any kind.
>

Transposing this discussion to our udp-notif, for the sake of consistency,
is the WG considering not to create IANA pools for the protocol code points
defining options and encoding types?
Are we saying NETCONF no longer uses IANA to organize their protocol code
points? I have no strong opinion on this, as our goal as developers is to
have the IETF tell us which values to use for these codes,
but this seems like a radical change of approach compared to what I've been
used to, so I'd like to make sure I understand this is what is going on ;)

Regards,

Pierre.

---

From: Mahesh Jethanandani <[email-masked]>
Date: Thu, 22 Jul 2021 11:04:49 -0700

Hi Pierre,

> On Jul 22, 2021, at 4:43 AM, Pierre Francois <[email-masked]> wrote:
> 
> Kent, 
> 
> Transposing this discussion to our udp-notif, for the sake of consistency, is the WG considering not to create IANA pools for the protocol code points defining options and encoding types? 
> Are we saying NETCONF no longer uses IANA to organize their protocol code points? I have no strong opinion on this, as our goal as developers is to have the IETF tell us which values to use for these codes, 
> but this seems like a radical change of approach compared to what I've been used to, so I'd like to make sure I understand this is what is going on ;)

The proposal, as I understand from Rob is to use identities to define capabilities. For example, a new module called “iana-notif-transport-capabilities” would define a base identity called:

  identity transport-capabilities {
    description
      "Base identity from which identities describing transport
       capabilities are derived.";
  }

Other capabilities would then derive of this base identity to define new capabilities. See attached module for a more complete example.

This module will be a IANA maintained module. However, the difference is that while the module will be registered with IANA, you do not need a registry to maintain the capabilities. Instead, anybody can create a new module, import the base identity from this IANA module, and define a new capability.

Makes sense?

> 
> Regards, 
> 
> Pierre.
> 
> 
> 
> 
>  
> _______________________________________________
> netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf

Mahesh Jethanandani
[email-masked]

---

From: Pierre Francois <[email-masked]>
Date: Fri, 23 Jul 2021 09:26:36 +0200

Mahesh,

Le jeu. 22 juil. 2021 à 20:05, Mahesh Jethanandani <[email-masked]>
a écrit :

> but this seems like a radical change of approach compared to what I've
> been used to, so I'd like to make sure I understand this is what is going
> on ;)
>
>
> The proposal, as I understand from Rob is to use identities to define
> capabilities. For example, a new module called
> “iana-notif-transport-capabilities” would define a base identity called:
>
> Other capabilities would then derive of this base identity to define new
> capabilities. See attached module for a more complete example.
>
> This module will be a IANA maintained module. However, the difference is
> that while the module will be registered with IANA, you do not need a
> registry to maintain the capabilities. Instead, anybody can create a new
> module, import the base identity from this IANA module, and define a new
> capability.
>
> Makes sense?
>

For expressing capabilities, it seems to work, but the pools I was
referring to and discussing with you offline are for what I will find on
the wire for options and encoding types in the header.
For this to work I'd need the values explicited in the module so that I
know what to put in the code.
If anybody can create their own and decide which value will be on the wire
without a pool, we lose unicity, don't we?

Regards,

Pierre.

---

From: Mahesh Jethanandani <[email-masked]>
Date: Sat, 24 Jul 2021 13:08:33 -0700

Hi Pierre,

> On Jul 23, 2021, at 12:26 AM, Pierre Francois <[email-masked]> wrote:
> 
> Mahesh, 
> 
> Le jeu. 22 juil. 2021 à 20:05, Mahesh Jethanandani <[email-masked] <mailto:[email-masked]>> a écrit :
> Hi Pierre,
> 
>> On Jul 22, 2021, at 4:43 AM, Pierre Francois <[email-masked] <mailto:[email-masked]>> wrote:
>> 
>> Kent, 
>> 
> For expressing capabilities, it seems to work, but the pools I was referring to and discussing with you offline are for what I will find on the wire for options and encoding types in the header.
> For this to work I'd need the values explicited in the module so that I know what to put in the code. 
> If anybody can create their own and decide which value will be on the wire without a pool, we lose unicity, don't we?

You will notice that the thread starts with Rob’s message in the green, where he was specifically asking about capability advertisement. And so does my response. So this solution works for capabilities, but will not address the question you raise about code points. For that you might have to make a IANA registry request.

HTC. Thanks.

Mahesh Jethanandani
[email-masked]

---

From: Pierre Francois <[email-masked]>
Date: Sun, 25 Jul 2021 00:08:14 +0200

Hello Mahesh,

That's what I thought initially. I just followed the suggestion I received
from you to react to this thread when I mentioned the creation of these
pools planned for -04.
All is well then. If the wg agrees I'll add the IANA requests to the next
revision of the draft.

Thanks !
Cheers,

Pierre.

Le sam. 24 juil. 2021 à 22:08, Mahesh Jethanandani <[email-masked]>
a écrit :

> Le jeu. 22 juil. 2021 à 20:05, Mahesh Jethanandani <
> [email-masked]> a écrit :
>
>> Hi Pierre,
>>
>> Transposing this discussion to our udp-notif, for the sake of
>> consistency, is the WG considering not to create IANA pools for the
>> protocol code points defining options and encoding types?
> You will notice that the thread starts with Rob’s message in the green,
> where he was specifically asking about capability advertisement. And so
> does my response. So this solution works for capabilities, but will not
> address the question you raise about code points. For that you might have
> to make a IANA registry request.
>
> HTC. Thanks.
>
>
> Regards,
>
> Pierre.
>
>
> Mahesh Jethanandani
> [email-masked]
>
>
>
>
>
>

---

From: "Rob Wilton (rwilton)" <[email-masked]>
Date: Tue, 27 Jul 2021 16:25:49 +0000

Hi All,

Actually, my proposal was slightly different.

There is an IANA registry for AFIs and SAFIs, that is defined here Address Family Numbers (iana.org)<https://www.iana.org/assignments/address-family-numbers/address-family-numbers.xhtml> and here: Subsequent Address Family Identifiers (SAFI) Parameters (iana.org)<https://www.iana.org/assignments/safi-namespace/safi-namespace.xhtml>

There is also an IANA maintained YANG module registry (iana-routing-types YANG Module<https://www.iana.org/assignments/iana-routing-types/iana-routing-types.xhtml>) that defines enums values for these two above registries that is automatically maintained by IANA.  I.e., whenever either of the AFI or SAFI registries are updated then a new revision of the iana-routing-types.yang module is created to reflect those changes.  The instructions to IANA on how to create and maintain the iana-routing-types registry is defined in section 5.1 of RFC 8294.

This makes these values easily available to code that understands YANG, but that table of AFI/SAFI code points are also available to other protocols.

Another example is the IANA if-types registry that I believe is handled somewhat similarly (perhaps because the values are shared between SNMP and YANG).

But I agree with Kent/Mahesh that you don’t need to have IANA maintain these, and it could just be done using YANG modules defining new identities.  There are several choices here with different pros and cons (including the one that is currently documented).

Regards,
Rob

From: netconf <[email-masked]> On Behalf Of Mahesh Jethanandani
Sent: 22 July 2021 19:05
To: Pierre Francois <[email-masked]>
Cc: [email-masked]
Subject: Re: [netconf] Capability-fetching mechanisms

Hi Pierre,

On Jul 22, 2021, at 4:43 AM, Pierre Francois <[email-masked]<mailto:[email-masked]>> wrote:

Kent,

Makes sense?

Regards,

Pierre.

_______________________________________________
netconf mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/netconf

Mahesh Jethanandani
[email-masked]<mailto:[email-masked]>