- From: Kent Watsen <kent+ietf@watsen.net>
- Date: Wed, 6 May 2020 17:18:42 +0000
- To: Mark Nottingham <mnot@mnot.net>
- Cc: HTTP Working Group <ietf-http-wg@w3.org>, "netconf-chairs@ietf.org" <netconf-chairs@ietf.org>
- Message-ID: <01000171eaff2503-d978e760-f03b-416b-9208-f9a95d1ecadb-000000@email.amazonses.co>
Hi Mark.
> To help people understand what they're looking at, do you have any pointers to documents explaining what RESTCONF is, at a high level? Also, some context on what the model is intended to be used for would be really helpful.
Yes, of course, silly me! ;)
RESTCONF (RFC 8040) is an HTTP-variant of NETCONF (RFC 6241, RFC 4741), which is the network management protocol IETF defined roughly 15 years ago to replace SNMP. Whereas SNMP uses MIBs to define message structures, RESTCONF and NETCONF use YANG (RFC 7950, RFC 6020). NETCONF is purely an XML-based protocol, whereas RESTCONF uses media-types to define encodings, with current media-types including both JSON and XML.
For years now the IETF has been defining YANG “modules” to describe how to configure and monitor various aspects of a system, with primary emphasis on networking/routing protocols, firewall/ACLs, and the like. More recently there has been interest in also defining standard modules for system-level management (i.e., how to configure users, access control, Syslog, etc.).
Thus the desire to define YANG modules for configuring the RESTCONF/NETCONF servers (and clients) running on said networking gear was born. This is a problem that the NETCONF WG has been working on for nearly 5 years now and, thankfully, it seems that we’re now close to the end of that effort, with the suite of documents nearing a WG last call.
My previous message mentioned how there is a suite of drafts that define “groupings”, snippets of configuration that can be mixed-in to define all the configuration for a protocol stack. The below diagram depicts the relationship for all 9 IETF drafts in the suite of drafts (simply prefix “draft-ietf-netconf-“ to the name below to get the full draft name). Notice that the “restconf-client-server” draft depends on the “http-client-server” draft (what this email to the HTTP WG is about).
crypto-types
^ ^
/ \
/ \
trust-anchors keystore
^ ^------+ ^
| \ |
| +-----------+
| / \
tcp-client-server ssh-client-server tls-client-server http-client-server
^ ^ ^ ^ ^ ^
| | | | | |
| | | +----------+ | |
| | | | | |
| | | | | |
| +--------------|-------|------------+ | |
| | | | | |
| | | | | |
+--------------+ | | | | +--------+
| | | | | |
| | | | | |
netconf-client-server restconf-client-server
That’s likely enough context setting. Of course, please ask questions if there is a desire to know more at this level. What I think would be more interesting to you all is to see some examples, i.e., where the rubber hits the road…. ;)
Snippet from https://tools.ietf.org/html/draft-ietf-netconf-http-client-server-02#section-3.2 <https://tools.ietf.org/html/draft-ietf-netconf-http-client-server-02#section-3.2> (please visit to see full example):
<http-client>
<client-identity>
<basic>
<user-id>bob</user-id>
<password>secret</password>
</basic>
</client-identity>
</http-client>
This example illustrates how the “http-client-grouping” enables the client’s identity to be configured. Please recall from my previous message that “basic” is the *only* HTTP authentication scheme supported by the YANG module. If folks want to use others, whether standards-based or proprietary, they can be “augmented” (a YANG term) as needed.
Not depicted by this example, is that the “http-client-grouping” also supports the optional configuration of HTTP proxy server settings, in case it is necessary for the HTTP-client to egress thru a proxy server.
And that’s it! Just the "client-identity" and a "proxy-server” values can be configured in the “http-client-grouping".
PS: in case you’re wondering how the client knows what server to connect to, please note that the remote address/port (which can be a hostname) is configured in the “tcp-client-grouping” mix-in grouping and, likewise, an TLS-level client certificate would be configured in the “tls-client-grouping” mix-in grouping.
Snippet from https://tools.ietf.org/html/draft-ietf-netconf-http-client-server-02#section-4.2 <https://tools.ietf.org/html/draft-ietf-netconf-http-client-server-02#section-4.2> (please visit to see full example):
<http-server>
<server-name>foo.example.com</server-name>
<protocol-versions>
<protocol-version>HTTP/1.1</protocol-version>
<protocol-version>HTTP/2.0</protocol-version>
</protocol-versions>
</http-server>
This example illustrates how the “http-server-grouping” enables the HTTP server’s name and supported protocol versions to be configured.
Not depicted by this example, is that the “http-client-grouping” also supports the optional configuration of HTTP client accounts in order to authenticate incoming HTTP clients against. Consistent with what was mentioned before, only the “Basic” scheme is supported, while others can be augmented in if needed.
And that’s it! Just the “server-name”, “protocol-version”, and "client-authentication” values can be configured in the “http-server-grouping".
PS: in case you’re wondering how the server knows what address/port to listen on, please note that the local address/port is configured in the “tcp-server-grouping” mix-in grouping and, likewise, an TLS-level server certificate would be configured in the “tls-server-grouping” mix-in grouping.
Hope that helps!
Kent
> On May 6, 2020, at 1:07 AM, Mark Nottingham <mnot@mnot.net> wrote:
>
> Hi Kent,
>
> Thanks for that.
>
> To help people understand what they're looking at, do you have any pointers to documents explaining what RESTCONF is, at a high level? Also, some context on what the model is intended to be used for would be really helpful.
>
> Cheers,
>
>
>> On 6 May 2020, at 3:23 am, Kent Watsen <kent+ietf@watsen.net> wrote:
>>
>> Hi Folks,
>>
>> This I-D should be of interest to you: draft-ietf-netconf-http-client-server. It would be great to get some feedback from the HTTP group!
>>
>> Mark had asked me to present this work to the HTTP WG @ IETF 107, but I never saw a call for presentations for that meeting. Upon seeing the recent HTTP virtual interim announcement, I again reached out to Mark, but noting that the VI agenda is packed, he asked me to send an email to the list, which is what this message is about.
>>
>> Please note that the I-D is being run out the NETCONF WG because it is part of a suite of drafts that have been in progress to configure NETCONF and RESTCONF clients and servers…and HTTP is a base protocol for RESTCONF.
>>
>> The NETCONF WG’s goal is for this I-D to be minimally viable. A previous version had more things in it (e.g., all HTTP authentication schemes), but has since been stripped down to the core. Its current scope is minimally sufficient for the NETCONF WG's goal…there is no desire to increase its scope on our side.
>>
>> To get a feel for how the configuration model defined in this draft ties in with the suite of a drafts mentioned above, please see the simplified YANG tree diagrams (RFC 8340) below, pulled from the draft-ietf-netconf-restconf-client-server draft. [Pro tip: the ‘u’ in the diagram stands for “uses”, i.e., where a YANG model pulls in a definition from a grouping.]
>>
>> FWIW, RESTCONF MUST be layered on top of TLS, as depicted in the “restconf-client” model below but, as a RESTCONF server MAY be fronted by a TLS-terminator (i.e., a load balancer), the “restconf-server” model supports both cases with and
>> without the "tls-server-grouping” grouping mixed in. Important: the ability to mix-in protocol layers as needed is a key aspect of the general approach taken by the NETCONF WG.
>>
>>
>> grouping restconf-client
>> +-- (transport)
>> +--:(https)
>> +-- https
>> +-- tcp-client-parameters
>> | +---u tcpc:tcp-client-grouping
>> +-- tls-client-parameters
>> | +---u tlsc:tls-client-grouping
>> +-- http-client-parameters
>> | +---u httpc:http-client-grouping <-- defined by this I-D
>> +-- restconf-client-parameters
>> +---u rcs:restconf-client-grouping
>>
>>
>> grouping restconf-server
>> +-- (transport)
>> +--:(http)
>> | +-- http
>> | +-- external-endpoint!
>> | | +-- address inet:ip-address
>> | | +-- port? inet:port-number
>> | +-- tcp-server-parameters
>> | | +---u tcps:tcp-server-grouping
>> | +-- http-server-parameters
>> | | +---u https:http-server-grouping <-- defined by this I-D
>> | +-- restconf-server-parameters
>> | +---u rcs:restconf-server-grouping
>> +--:(https)
>> +-- https
>> +-- tcp-server-parameters
>> | +---u tcps:tcp-server-grouping
>> +-- tls-server-parameters
>> | +---u tlss:tls-server-grouping
>> +-- http-server-parameters
>> | +---u https:http-server-grouping <-- defined by this I-D
>> +-- restconf-server-parameters
>> +---u rcs:restconf-server-grouping
>>
>>
>> PS: I’ve CC-ed the NETCONF chairs for visibility, rather than CC the NETCONF list. If needed, I’ll be the liaison between the two WGs if needed, or we can cross-post if that is deemed better...
>>
>> Kent (the author of the I-D)
>
> --
> Mark Nottingham https://www.mnot.net/
>
>
Received on Wednesday, 6 May 2020 17:18:55 UTC