Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8343

A YANG Data Model for Interface Management

Pages: 49
Proposed Standard
Obsoletes:  7223
Part 3 of 3 – Pages 34 to 49
First   Prev   None

Top   ToC   RFC8343 - Page 34   prevText

6. IANA Considerations

This document registers a URI in the "IETF XML Registry" [RFC3688]. Following the format in RFC 3688, the following registration has been made. URI: urn:ietf:params:xml:ns:yang:ietf-interfaces Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace.
Top   ToC   RFC8343 - Page 35
   This document registers a YANG module in the "YANG Module Names"
   registry [RFC6020].

     name:         ietf-interfaces
     namespace:    urn:ietf:params:xml:ns:yang:ietf-interfaces
     prefix:       if
     reference:    RFC 8343

7. Security Considerations

The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC5246]. The NETCONF access control model [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. These are the subtrees and data nodes and their sensitivity/vulnerability: /interfaces/interface: This list specifies the configured interfaces on a device. Unauthorized access to this list could cause the device to ignore packets it should receive and process. /interfaces/interface/enabled: This leaf controls whether or not an interface is enabled. Unauthorized access to this leaf could cause the device to ignore packets it should receive and process.
Top   ToC   RFC8343 - Page 36

8. References

8.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>. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/info/rfc5246>. [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>. [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>. [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/rfc6991>. [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/info/rfc7950>. [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
Top   ToC   RFC8343 - Page 37
   [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>.

   [RFC8341]  Bierman, A. and M. Bjorklund, "Network Configuration
              Access Control Model", STD 91, RFC 8341,
              DOI 10.17487/RFC8341, March 2018,
              <https://www.rfc-editor.org/info/rfc8341>.

   [RFC8342]  Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
              and R. Wilton, "Network Management Datastore Architecture
              (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
              <https://www.rfc-editor.org/info/rfc8342>.

8.2. Informative References

[RFC7224] Bjorklund, M., "IANA Interface Type YANG Module", RFC 7224, DOI 10.17487/RFC7224, May 2014, <https://www.rfc-editor.org/info/rfc7224>. [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/info/rfc8340>.
Top   ToC   RFC8343 - Page 38

Appendix A. Example: Ethernet Interface Module

This section gives a simple example of how an Ethernet interface module could be defined. It demonstrates how media-specific configuration parameters can be conditionally augmented to the generic interface list. It also shows how operational state parameters can be conditionally augmented to the operational interface list. The example is not intended as a complete module for Ethernet configuration. module example-ethernet { namespace "http://example.com/ethernet"; prefix "eth"; import ietf-interfaces { prefix if; } import iana-if-type { prefix ianaift; } // configuration and state parameters for Ethernet interfaces augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:ethernetCsmacd'"; container ethernet { container transmission { choice transmission-params { case auto { leaf auto-negotiate { type empty; } } case manual { container manual { leaf duplex { type enumeration { enum "half"; enum "full"; } } leaf speed { type enumeration { enum "10Mb"; enum "100Mb"; enum "1Gb"; enum "10Gb"; }
Top   ToC   RFC8343 - Page 39
                 }
               }
             }
           }
           leaf duplex {
             type enumeration {
               enum "half";
               enum "full";
             }
             config false;
           }
         }
         // other Ethernet-specific params...
       }
     }
   }

Appendix B. Example: Ethernet Bonding Interface Module

This section gives an example of how interface layering can be defined. An Ethernet bonding interface that bonds several Ethernet interfaces into one logical interface is defined. module example-ethernet-bonding { namespace "http://example.com/ethernet-bonding"; prefix "bond"; import ietf-interfaces { prefix if; } import iana-if-type { prefix ianaift; } augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:ieee8023adLag'"; leaf-list slave-if { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" + "/if:type = 'ianaift:ethernetCsmacd'" { description "The type of a slave interface must be 'ethernetCsmacd'."; } } leaf bonding-mode { type enumeration { enum round-robin;
Top   ToC   RFC8343 - Page 40
           enum active-backup;
           enum broadcast;
         }
       }
       // other bonding config params, failover times, etc.
     }
   }

Appendix C. Example: VLAN Interface Module

This section gives an example of how a VLAN interface module can be defined. module example-vlan { namespace "http://example.com/vlan"; prefix "vlan"; import ietf-interfaces { prefix if; } import iana-if-type { prefix ianaift; } augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:ethernetCsmacd' or if:type = 'ianaift:ieee8023adLag'"; leaf vlan-tagging { type boolean; default false; } } augment "/if:interfaces/if:interface" { when "if:type = 'ianaift:l2vlan'"; leaf base-interface { type if:interface-ref; must "/if:interfaces/if:interface[if:name = current()]" + "/vlan:vlan-tagging = 'true'" { description "The base interface must have VLAN tagging enabled."; } } leaf vlan-id { type uint16 { range "1..4094"; }
Top   ToC   RFC8343 - Page 41
         must "../base-interface" {
           description
             "If a vlan-id is defined, a base-interface must
              be specified.";
         }
       }
     }
   }

Appendix D. Example: NETCONF <get-config> Reply

This section gives an example of a reply to the NETCONF <get-config> request for the running configuration datastore for a device that implements the example data models above. <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101"> <data> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type" xmlns:vlan="http://example.com/vlan"> <interface> <name>eth0</name> <type>ianaift:ethernetCsmacd</type> <enabled>false</enabled> </interface> <interface> <name>eth1</name> <type>ianaift:ethernetCsmacd</type> <enabled>true</enabled> <vlan:vlan-tagging>true</vlan:vlan-tagging> </interface> <interface> <name>eth1.10</name> <type>ianaift:l2vlan</type> <enabled>true</enabled> <vlan:base-interface>eth1</vlan:base-interface> <vlan:vlan-id>10</vlan:vlan-id> </interface> <interface> <name>lo1</name> <type>ianaift:softwareLoopback</type>
Top   ToC   RFC8343 - Page 42
           <enabled>true</enabled>
         </interface>

       </interfaces>
     </data>
   </rpc-reply>

Appendix E. Example: NETCONF <get-data> Reply

This section gives an example of a reply to the NETCONF <get-data> request for the operational state datastore for a device that implements the example data models above. This example uses the "origin" annotation, which is defined in the module "ietf-origin" [RFC8342]. <rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101"> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-datastores"> <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces" xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type" xmlns:vlan="http://example.com/vlan" xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"> <interface or:origin="or:intended"> <name>eth0</name> <type>ianaift:ethernetCsmacd</type> <enabled>false</enabled> <admin-status>down</admin-status> <oper-status>down</oper-status> <if-index>2</if-index> <phys-address>00:01:02:03:04:05</phys-address> <statistics> <discontinuity-time> 2013-04-01T03:00:00+00:00 </discontinuity-time> <!-- counters now shown here --> </statistics> </interface> <interface or:origin="or:intended"> <name>eth1</name> <type>ianaift:ethernetCsmacd</type> <enabled>true</enabled> <admin-status>up</admin-status> <oper-status>up</oper-status>
Top   ToC   RFC8343 - Page 43
           <if-index>7</if-index>
           <phys-address>00:01:02:03:04:06</phys-address>
           <higher-layer-if>eth1.10</higher-layer-if>
           <statistics>
             <discontinuity-time>
               2013-04-01T03:00:00+00:00
             </discontinuity-time>
             <!-- counters now shown here -->
           </statistics>
           <vlan:vlan-tagging>true</vlan:vlan-tagging>
         </interface>

         <interface or:origin="or:intended">
           <name>eth1.10</name>
           <type>ianaift:l2vlan</type>
           <enabled>true</enabled>
           <admin-status>up</admin-status>
           <oper-status>up</oper-status>
           <if-index>9</if-index>
           <lower-layer-if>eth1</lower-layer-if>
           <statistics>
             <discontinuity-time>
               2013-04-01T03:00:00+00:00
             </discontinuity-time>
             <!-- counters now shown here -->
           </statistics>
           <vlan:base-interface>eth1</vlan:base-interface>
           <vlan:vlan-id>10</vlan:vlan-id>
         </interface>

         <!-- This interface is not configured -->
         <interface or:origin="or:system">
           <name>eth2</name>
           <type>ianaift:ethernetCsmacd</type>
           <admin-status>down</admin-status>
           <oper-status>down</oper-status>
           <if-index>8</if-index>
           <phys-address>00:01:02:03:04:07</phys-address>
           <statistics>
             <discontinuity-time>
               2013-04-01T03:00:00+00:00
             </discontinuity-time>
             <!-- counters now shown here -->
           </statistics>
         </interface>

         <interface or:origin="or:intended">
           <name>lo1</name>
Top   ToC   RFC8343 - Page 44
           <type>ianaift:softwareLoopback</type>
           <enabled>true</enabled>
           <admin-status>up</admin-status>
           <oper-status>up</oper-status>
           <if-index>1</if-index>
           <statistics>
             <discontinuity-time>
               2013-04-01T03:00:00+00:00
             </discontinuity-time>
             <!-- counters now shown here -->
           </statistics>
         </interface>

       </interfaces>
     </data>
   </rpc-reply>

Appendix F. Examples: Interface Naming Schemes

This section gives examples of some implementation strategies. The examples make use of the example data model "example-vlan" (see Appendix C) to show how user-controlled interfaces can be configured.

F.1. Router with Restricted Interface Names

In this example, a router has support for 4 line cards, each with 8 ports. The slots for the cards are physically numbered from 0 to 3, and the ports on each card from 0 to 7. Each card has Fast Ethernet or Gigabit Ethernet ports. The device-specific names for these physical interfaces are "fastethernet-N/M" or "gigabitethernet-N/M". The name of a VLAN interface is restricted to the form "<physical-interface-name>.<subinterface-number>". It is assumed that the operator is aware of this naming scheme. The implementation auto-initializes the value for "type" based on the interface name. The NETCONF server does not advertise the "arbitrary-names" feature in the <hello> message.
Top   ToC   RFC8343 - Page 45
   An operator can configure a physical interface by sending an
   <edit-config> containing:

     <interface nc:operation="create">
       <name>fastethernet-1/0</name>
     </interface>

   When the server processes this request, it will set the leaf "type"
   to "ianaift:ethernetCsmacd".  Thus, if the client performs a
   <get-config> right after the <edit-config> above, it will get:

     <interface>
       <name>fastethernet-1/0</name>
       <type>ianaift:ethernetCsmacd</type>
     </interface>

   The client can configure a VLAN interface by sending an <edit-config>
   containing:

     <interface nc:operation="create">
       <name>fastethernet-1/0.10005</name>
       <type>ianaift:l2vlan</type>
       <vlan:base-interface>fastethernet-1/0</vlan:base-interface>
       <vlan:vlan-id>5</vlan:vlan-id>
     </interface>

   If the client tries to change the type of the physical interface with
   an <edit-config> containing:

     <interface nc:operation="merge">
       <name>fastethernet-1/0</name>
       <type>ianaift:tunnel</type>
     </interface>

   then the server will reply with an "invalid-value" error, since the
   new type does not match the name.

F.2. Router with Arbitrary Interface Names

In this example, a router has support for 4 line cards, each with 8 ports. The slots for the cards are physically numbered from 0 to 3, and the ports on each card from 0 to 7. Each card has Fast Ethernet or Gigabit Ethernet ports. The device-specific names for these physical interfaces are "fastethernet-N/M" or "gigabitethernet-N/M".
Top   ToC   RFC8343 - Page 46
   The implementation does not restrict the user-controlled interface
   names.  This allows an operator to more easily apply the interface
   configuration to a different interface.  However, the additional
   level of indirection also makes it a bit more complex to map
   interface names found in other protocols to configuration entries.

   The NETCONF server advertises the "arbitrary-names" feature in the
   <hello> message.

   Physical interfaces are configured as in Appendix F.1.

   An operator can configure a VLAN interface by sending an
   <edit-config> containing:

     <interface nc:operation="create">
       <name>acme-interface</name>
       <type>ianaift:l2vlan</type>
       <vlan:base-interface>fastethernet-1/0</vlan:base-interface>
       <vlan:vlan-id>5</vlan:vlan-id>
     </interface>

   If necessary, the operator can move the configuration named
   "acme-interface" over to a different physical interface with an
   <edit-config> containing:

     <interface nc:operation="merge">
       <name>acme-interface</name>
       <vlan:base-interface>fastethernet-1/1</vlan:base-interface>
     </interface>

F.3. Ethernet Switch with Restricted Interface Names

In this example, an Ethernet switch has a number of ports, each identified by a simple port number. The device-specific names for the physical interfaces are numbers that match the physical port number. An operator can configure a physical interface by sending an <edit-config> containing: <interface nc:operation="create"> <name>6</name> </interface>
Top   ToC   RFC8343 - Page 47
   When the server processes this request, it will set the leaf "type"
   to "ianaift:ethernetCsmacd".  Thus, if the client performs a
   <get-config> right after the <edit-config> above, it will get:

     <interface>
       <name>6</name>
       <type>ianaift:ethernetCsmacd</type>
     </interface>

F.4. Generic Host with Restricted Interface Names

In this example, a generic host has interfaces named by the kernel. The system identifies the physical interface by the name assigned by the operating system to the interface. The name of a VLAN interface is restricted to the form "<physical-interface-name>:<vlan-number>". The NETCONF server does not advertise the "arbitrary-names" feature in the <hello> message. An operator can configure an interface by sending an <edit-config> containing: <interface nc:operation="create"> <name>eth8</name> </interface> When the server processes this request, it will set the leaf "type" to "ianaift:ethernetCsmacd". Thus, if the client performs a <get-config> right after the <edit-config> above, it will get: <interface> <name>eth8</name> <type>ianaift:ethernetCsmacd</type> </interface> The client can configure a VLAN interface by sending an <edit-config> containing: <interface nc:operation="create"> <name>eth8:5</name> <type>ianaift:l2vlan</type> <vlan:base-interface>eth8</vlan:base-interface> <vlan:vlan-id>5</vlan:vlan-id> </interface>
Top   ToC   RFC8343 - Page 48

F.5. Generic Host with Arbitrary Interface Names

In this example, a generic host has interfaces named by the kernel. The system identifies the physical interface by the name assigned by the operating system to the interface. The implementation does not restrict the user-controlled interface names. This allows an operator to more easily apply the interface configuration to a different interface. However, the additional level of indirection also makes it a bit more complex to map interface names found in other protocols to configuration entries. The NETCONF server advertises the "arbitrary-names" feature in the <hello> message. Physical interfaces are configured as in Appendix F.4. An operator can configure a VLAN interface by sending an <edit-config> containing: <interface nc:operation="create"> <name>acme-interface</name> <type>ianaift:l2vlan</type> <vlan:base-interface>eth8</vlan:base-interface> <vlan:vlan-id>5</vlan:vlan-id> </interface> If necessary, the operator can move the configuration named "acme-interface" over to a different physical interface with an <edit-config> containing: <interface nc:operation="merge"> <name>acme-interface</name> <vlan:base-interface>eth3</vlan:base-interface> </interface>
Top   ToC   RFC8343 - Page 49

Acknowledgments

The author wishes to thank Alexander Clemm, Per Hedeland, Ladislav Lhotka, and Juergen Schoenwaelder for their helpful comments.

Author's Address

Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com