doc: Add RFC documents

1 files changed, 415 insertions, 0 deletions

diff --git a/doc/rfc/rfc9296.txt b/doc/rfc/rfc9296.txt
new file mode 100644
index 0000000..898cda7
--- /dev/null
+++ b/doc/rfc/rfc9296.txt
@@ -0,0 +1,415 @@
+
+
+
+
+Independent Submission                                            D. Liu
+Request for Comments: 9296                                    J. Halpern
+Category: Informational                                         C. Zhang
+ISSN: 2070-1721                                                 Ericsson
+                                                             August 2022
+
+
+  ifStackTable for the Point-to-Point (P2P) Interface over a LAN Type:
+                        Definition and Examples
+
+Abstract
+
+   RFC 5309 defines the Point-to-Point (P2P) circuit type, one of the
+   two circuit types used in the link-state routing protocols, and
+   highlights that it is important to identify the correct circuit type
+   when forming adjacencies, flooding link-state database packets, and
+   monitoring the link state.
+
+   This document provides advice about the ifStack for the P2P interface
+   over a LAN Type to facilitate operational control, maintenance, and
+   statistics.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This is a contribution to the RFC Series, independently of any other
+   RFC stream.  The RFC Editor has chosen to publish this document at
+   its discretion and makes no statement about its value for
+   implementation or deployment.  Documents approved for publication by
+   the RFC Editor are not candidates for any level of Internet Standard;
+   see Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc9296.
+
+Copyright Notice
+
+   Copyright (c) 2022 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.
+
+Table of Contents
+
+   1.  Introduction
+   2.  Requirements Language
+   3.  Interface Stack Table for P2P Interface Type
+     3.1.  P2P Interface: higher-layer-if and lower-layer-if
+     3.2.  P2P Interface Statistics
+     3.3.  P2P Interface Administrative State
+   4.  Security Considerations
+   5.  IANA Considerations
+   6.  References
+     6.1.  Normative References
+     6.2.  Informative References
+   Appendix A.  Examples
+   Acknowledgements
+   Authors' Addresses
+
+1.  Introduction
+
+   [RFC5309] defines the Point-to-Point (P2P) circuit type and
+   highlights that it is important to identify the correct circuit type
+   when forming adjacencies, flooding link-state database packets, and
+   monitoring the link state.
+
+   To simplify configuration and operational control, it is helpful to
+   represent the fact that an interface is to be considered a P2P
+   interface over a LAN type explicitly in the interface stack.  This
+   enables, for example, routing protocols to automatically inherit the
+   correct operating mode from the interface stack without further
+   configuration (i.e., there is no need to explicitly configure the P2P
+   interface in routing protocols).
+
+   It is helpful to map the P2P interface over a LAN type in the
+   interface management stack table.  If no entry specifies the lower
+   layer of the P2P interface, then management tools lose the ability to
+   retrieve and measure properties specific to lower layers.
+
+   In standard network management protocols that make use of
+   ifStackTables, the P2P interface over a LAN type is intended to be
+   used solely as a means to signal that the upper-layer interface of
+   link-data layer is a P2P interface.  Thus, the upper and lower layers
+   of P2P over a LAN type are expected to apply appropriate semantics.
+   In general, the higher layer of a P2P over a LAN type SHOULD be
+   "ipForward" (value 142 in [Assignment]), and the lower layer of P2P
+   over a LAN type SHOULD be any appropriate link-data layer of
+   "ipForward".
+
+   The assignment of 303 as the value for the p2pOverLan ifType was made
+   by Expert Review (see [Assignment] and [RFC8126]).  The purpose of
+   this document is to serve as a reference for ifType 303 by suggesting
+   how the ifStackTable for the P2P interface over a LAN type is to be
+   used and providing examples.
+
+   It should be noted that this document reflects the operating model
+   used on some routers.  Other routers that use different models may
+   not represent a P2P as a separate interface.
+
+2.  Requirements Language
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+3.  Interface Stack Table for P2P Interface Type
+
+3.1.  P2P Interface: higher-layer-if and lower-layer-if
+
+   If a device implements the IF-MIB [RFC2863], then each entry in the
+   "/interfaces/interface" list (see "A YANG Data Model for Interface
+   Management" [RFC8343]) in the operational state is typically mapped
+   to one ifEntry as required in [RFC8343].  Therefore, the P2P
+   interface over a LAN type should also be fully mapped to one ifEntry
+   by defining the "ifStackTable" ("higher-layer-if" and "lower-layer-
+   if", defined in [RFC8343]).
+
+   In the ifStackTable, the higher layer of the P2P interface over a LAN
+   type SHALL be network layer "ipForward" to enable IP routing, and the
+   lower layer of the P2P interface over a LAN type SHOULD be any link-
+   data layer that can be bound to "ipForward", including
+   "ethernetCsmacd", "ieee8023adLag", "l2vlan", and so on (defined in
+   the iana-if-type YANG module [IANA-ifTYPE]).
+
+   The P2P interface over the LAN type ifStackTable can be defined along
+   the lines of the following example, which complies with [RFC8343] and
+   [RFC6991].  In the example, "lower-layer-if" takes "ethernetCsmacd",
+   but, in fact, "lower-layer-if" can be any other available link-data
+   layer.  See Appendix A for more examples.
+
+   <CODE BEGINS>
+               <interface>
+                 <name>isis_int</name>
+                 <type>ianaift:ipForward</type>
+               </interface>
+
+               <interface>
+                 <name>eth1</name>
+                 <type>ianaift:ethernetCsmacd</type>
+               </interface>
+
+               <interface>
+                 <name>p2p</name>
+                 <type>ianaift:p2pOverLan</type>
+                 <higher-layer-if>isis_int</higher-layer-if>
+                 <lower-layer-if>eth1</lower-layer-if>
+                 <enabled>false</enabled>
+                 <admin-status>down</admin-status>
+                 <oper-status>down</oper-status>
+                 <statistics>
+                   <discontinuity-time>
+                     2021-04-01T03:00:00+00:00
+                   </discontinuity-time>
+                   <!-- counters now shown here -->
+                 </statistics>
+               </interface>
+   <CODE ENDS>
+
+                                  Figure 1
+
+3.2.  P2P Interface Statistics
+
+   Because multiple IP interfaces can be bound to one physical port, the
+   statistics on the physical port SHOULD be a complete set that
+   includes statistics of all upper-layer interfaces.  Therefore, each
+   P2P interface collects and displays traffic that has been sent to it
+   via higher layers or received from it via lower layers.
+
+3.3.  P2P Interface Administrative State
+
+   The P2P interface can be shut down independently of the underlying
+   interface.
+
+   If the P2P interface is administratively up, then the "oper-status"
+   (defined in [RFC8343]) of that interface SHALL fully reflect the
+   state of the underlying interface; if the P2P interface is
+   administratively down, then the "oper-status" of that interface SHALL
+   be down.  Examples can be found in Appendix A.
+
+4.  Security Considerations
+
+   The writable attribute "admin-status" of the p2povervlan ifType is
+   inherited from [RFC8343].  Other objects associated with the
+   p2povervlan ifType are read-only.  With this in mind, the
+   considerations discussed in Section 7 of [RFC8343] otherwise apply to
+   the p2povervlan ifType.
+
+5.  IANA Considerations
+
+   In the "Interface Types (ifType)" registry, value 303 is assigned to
+   p2pOverLan [Assignment].  As this document explains how the
+   p2pOverLan (303) ifType is to be used, IANA has amended the reference
+   for p2pOverLan (303) to point to this document (instead of [RFC5309])
+   and made a similar amendment in the YANG iana-if-type module
+   [IANA-ifTYPE] (originally specified in [RFC7224]).
+
+6.  References
+
+6.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC2863]  McCloghrie, K. and F. Kastenholz, "The Interfaces Group
+              MIB", RFC 2863, DOI 10.17487/RFC2863, June 2000,
+              <https://www.rfc-editor.org/info/rfc2863>.
+
+   [RFC5309]  Shen, N., Ed. and A. Zinin, Ed., "Point-to-Point Operation
+              over LAN in Link State Routing Protocols", RFC 5309,
+              DOI 10.17487/RFC5309, October 2008,
+              <https://www.rfc-editor.org/info/rfc5309>.
+
+   [RFC7224]  Bjorklund, M., "IANA Interface Type YANG Module",
+              RFC 7224, DOI 10.17487/RFC7224, May 2014,
+              <https://www.rfc-editor.org/info/rfc7224>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
+              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
+              <https://www.rfc-editor.org/info/rfc8343>.
+
+6.2.  Informative References
+
+   [Assignment]
+              IANA, "Interface Types (ifType)",
+              <https://www.iana.org/assignments/smi-numbers>.
+
+   [IANA-ifTYPE]
+              IANA, "YANG Module Names",
+              <https://www.iana.org/assignments/yang-parameters>.
+
+   [RFC6991]  Schoenwaelder, J., Ed., "Common YANG Data Types",
+              RFC 6991, DOI 10.17487/RFC6991, July 2013,
+              <https://www.rfc-editor.org/info/rfc6991>.
+
+   [RFC8126]  Cotton, M., Leiba, B., and T. Narten, "Guidelines for
+              Writing an IANA Considerations Section in RFCs", BCP 26,
+              RFC 8126, DOI 10.17487/RFC8126, June 2017,
+              <https://www.rfc-editor.org/info/rfc8126>.
+
+Appendix A.  Examples
+
+   If the underlying interface is a VLAN sub-interface, the
+   ifStackTable should be defined as:
+
+   <CODE BEGINS>
+             <interface>
+               <name>isis_int</name>
+               <type>ianaift:ipForward</type>
+             </interface>
+
+             <interface>
+               <name>eth1_valn1</name>
+               <type>ianaift:l2vlan</type>
+             </interface>
+
+             <interface>
+               <name>p2p</name>
+               <type>ianaift:p2pOverLan</type>
+               <higher-layer-if>isis_int</higher-layer-if>
+               <lower-layer-if>eth1_valn1</lower-layer-if>
+               <enabled>false</enabled>
+               <admin-status>down</admin-status>
+               <oper-status>down</oper-status>
+               <statistics>
+                 <discontinuity-time>
+                   2021-04-01T03:00:00+00:00
+                 </discontinuity-time>
+                 <!-- counters now shown here -->
+               </statistics>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 2
+
+   If the underlying interface is Link Aggregation Group (LAG), the
+   ifStackTable should be defined as:
+
+   <CODE BEGINS>
+             <interface>
+               <name>isis_int</name>
+               <type>ianaift:ipForward</type>
+             </interface>
+
+             <interface>
+               <name>eth1_lag1</name>
+               <type>ianaift:ieee8023adLag</type>
+             </interface>
+
+             <interface>
+               <name>p2p</name>
+               <type>ianaift:p2pOverLan</type>
+               <higher-layer-if>isis_int</higher-layer-if>
+               <lower-layer-if>eth1_lag1</lower-layer-if>
+               <enabled>false</enabled>
+               <admin-status>down</admin-status>
+               <oper-status>down</oper-status>
+               <statistics>
+                 <discontinuity-time>
+                   2021-04-01T03:00:00+00:00
+                 </discontinuity-time>
+                 <!-- counters now shown here -->
+               </statistics>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 3
+
+   If the P2P interface and underlying interface are both
+   administratively up and the underlying interface operational status
+   is up:
+
+   <CODE BEGINS>
+             <interface>
+                <name>p2p</name>
+                <type>ianaift:p2pOverLan</type>
+                <higher-layer-if>isis_int</higher-layer-if>
+                <lower-layer-if>eth1</lower-layer-if>
+                <admin-status>up</admin-status>
+                <oper-status>up</oper-status>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 4
+
+   If the P2P interface and underlying interface are administratively up
+   but the underlying interface operational status is down:
+
+   <CODE BEGINS>
+             <interface>
+                <name>p2p</name>
+                <type>ianaift:p2pOverLan</type>
+                <higher-layer-if>isis_int</higher-layer-if>
+                <lower-layer-if>eth1</lower-layer-if>
+                <admin-status>up</admin-status>
+                <oper-status>down</oper-status>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 5
+
+   If the P2P interface is administratively down:
+
+   <CODE BEGINS>
+             <interface>
+                <name>p2p</name>
+                <type>ianaift:p2pOverLan</type>
+                <higher-layer-if>isis_int</higher-layer-if>
+                <lower-layer-if>eth1</lower-layer-if>
+                <admin-status>down</admin-status>
+                <oper-status>down</oper-status>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 6
+
+   If the P2P interface is administratively up but the underlying
+   interface is administratively down:
+
+   <CODE BEGINS>
+             <interface>
+                <name>p2p</name>
+                <type>ianaift:p2pOverLan</type>
+                <higher-layer-if>isis_int</higher-layer-if>
+                <lower-layer-if>eth1</lower-layer-if>
+                <admin-status>up</admin-status>
+                <oper-status>down</oper-status>
+             </interface>
+   <CODE ENDS>
+
+                                  Figure 7
+
+Acknowledgements
+
+   The authors would like to thank Rob Wilton for his reviews and
+   valuable comments and suggestions.
+
+Authors' Addresses
+
+   Daiying Liu
+   Ericsson
+   No.5 Lize East Street
+   Beijing
+   100102
+   China
+   Email: harold.liu@ericsson.com
+
+
+   Joel Halpern
+   Ericsson
+   Email: joel.halpern@ericsson.com
+
+
+   Congjie Zhang
+   Ericsson
+   Email: congjie.zhang@ericsson.com