A YANG Data Model for Interface Management
draft-ietf-netmod-interfaces-cfg-08

Internet-Draft          YANG Interface Management          November 2012

   <CODE ENDS>

Bjorklund                 Expires May 19, 2013                 [Page 22]
Internet-Draft          YANG Interface Management          November 2012

6.  IANA Considerations

   This document registers a URI in the IETF XML registry [RFC3688].
   Following the format in RFC 3688, the following registration is
   requested to be made.

        URI: urn:ietf:params:xml:ns:yang:ietf-interfaces

        Registrant Contact: The IESG.

        XML: N/A, the requested URI is an XML namespace.

   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 XXXX

Bjorklund                 Expires May 19, 2013                 [Page 23]
Internet-Draft          YANG Interface Management          November 2012

7.  Security Considerations

   The YANG module defined in this memo is designed to be accessed via
   the NETCONF protocol [RFC6241].  The lowest NETCONF layer is the
   secure transport layer and the mandatory-to-implement secure
   transport is SSH [RFC6242].

   There are a number of data nodes defined in the YANG module which 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 if an interface is
      enabled or not.  Unauthorized access to this leaf could cause the
      device to ignore packets it should receive and process.

Bjorklund                 Expires May 19, 2013                 [Page 24]
Internet-Draft          YANG Interface Management          November 2012

8.  Acknowledgments

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

Bjorklund                 Expires May 19, 2013                 [Page 25]
Internet-Draft          YANG Interface Management          November 2012

9.  References

9.1.  Normative References

   [I-D.ietf-netmod-iana-if-type]
              Bjorklund, M., "IANA Interface Type and Address Family
              YANG Modules", draft-ietf-netmod-iana-if-type-02 (work in
              progress), April 2012.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2863]  McCloghrie, K. and F. Kastenholz, "The Interfaces Group
              MIB", RFC 2863, June 2000.

   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
              January 2004.

   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
              Network Configuration Protocol (NETCONF)", RFC 6020,
              October 2010.

9.2.  Informative References

   [RFC2579]  McCloghrie, K., Ed., Perkins, D., Ed., and J.
              Schoenwaelder, Ed., "Textual Conventions for SMIv2",
              STD 58, RFC 2579, April 1999.

   [RFC6241]  Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
              Bierman, "Network Configuration Protocol (NETCONF)",
              RFC 6241, June 2011.

   [RFC6242]  Wasserman, M., "Using the NETCONF Protocol over Secure
              Shell (SSH)", RFC 6242, June 2011.

Bjorklund                 Expires May 19, 2013                 [Page 26]
Internet-Draft          YANG Interface Management          November 2012

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 is not intended as a complete module for
   ethernet configuration.

Bjorklund                 Expires May 19, 2013                 [Page 27]
Internet-Draft          YANG Interface Management          November 2012

   module ex-ethernet {
     namespace "http://example.com/ethernet";
     prefix "eth";

     import ietf-interfaces {
       prefix if;
     }

     augment "/if:interfaces/if:interface" {
       when "if:type = 'ethernetCsmacd'";

       container ethernet {
         must "../if:location" {
           description
             "An ethernet interface must specify the physical location
              of the ethernet hardware.";
         }
         choice transmission-params {
           case auto {
             leaf auto-negotiate {
               type empty;
             }
           }
           case manual {
             leaf duplex {
               type enumeration {
                 enum "half";
                 enum "full";
               }
             }
             leaf speed {
               type enumeration {
                 enum "10Mb";
                 enum "100Mb";
                 enum "1Gb";
                 enum "10Gb";
               }
             }
           }
         }
         // other ethernet specific params...
       }
     }
   }

Bjorklund                 Expires May 19, 2013                 [Page 28]
Internet-Draft          YANG Interface Management          November 2012

Appendix B.  Example: Ethernet Bonding Interface Module

   This section gives an example of how interface layering can be
   defined.  An ethernet bonding interface is defined, which bonds
   several ethernet interfaces into one logical interface.

   module ex-ethernet-bonding {
     namespace "http://example.com/ethernet-bonding";
     prefix "bond";

     import ietf-interfaces {
       prefix if;
     }

     augment "/if:interfaces/if:interface" {
       when "if:type = 'ieee8023adLag'";

       leaf-list slave-if {
         type if:interface-ref;
         must "/if:interfaces/if:interface[if:name = current()]"
            + "/if:type = 'ethernetCsmacd'" {
           description
             "The type of a slave interface must be ethernet.";
         }
       }
       leaf bonding-mode {
         type enumeration {
           enum round-robin;
           enum active-backup;
           enum broadcast;
         }
       }
       // other bonding config params, failover times etc.
     }
   }

Bjorklund                 Expires May 19, 2013                 [Page 29]
Internet-Draft          YANG Interface Management          November 2012

Appendix C.  Example: VLAN Interface Module

   This section gives an example of how a vlan interface module can be
   defined.

   module ex-vlan {
     namespace "http://example.com/vlan";
     prefix "vlan";

     import ietf-interfaces {
       prefix if;
     }

     augment "/if:interfaces/if:interface" {
       when "if:type = 'ethernetCsmacd' or
             if:type = 'ieee8023adLag'";
       leaf vlan-tagging {
         type boolean;
         default false;
       }
     }

     augment "/if:interfaces/if:interface" {
       when "if:type = '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";
         }
         must "../base-interface" {
           description
             "If a vlan-id is defined, a base-interface must
              be specified.";
         }
       }
     }
   }

Bjorklund                 Expires May 19, 2013                 [Page 30]
Internet-Draft          YANG Interface Management          November 2012

Appendix D.  Example: NETCONF <get> reply

   This section gives an example of a reply to the NETCONF <get> request
   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">
         <interface>
           <name>eth0</name>
           <type>ethernetCsmacd</type>
           <location>0</location>
           <enabled>true</enabled>
           <if-index>2</if-index>
         </interface>
         <interface>
           <name>eth1</name>
           <type>ethernetCsmacd</type>
           <location>1</location>
           <enabled>true</enabled>
           <if-index>7</if-index>
           <vlan-tagging
               xmlns="http://example.com/vlan">true</vlan-tagging>
         </interface>
       </interfaces>
     </data>
   </rpc-reply>

Bjorklund                 Expires May 19, 2013                 [Page 31]
Internet-Draft          YANG Interface Management          November 2012

Appendix E.  Examples: Interface Naming Schemes

   This section gives examples of some implementation strategies.

E.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- or
   gigabit-ethernet ports.

   The implementation restricts the names of the interfaces to one of
   "fastethernet-N/M" or "gigabitethernet-N/M".  The "location" of an
   interface is a string on the form "N/M".  The implementation auto-
   initializes the values for "type" and "location" based on the
   interface name.

   An operator can configure a new 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 "ethernetCsmacd" and "location" to "1/0".  Thus, if the client
   performs a <get-config> right after the <edit-config> above, it will
   get:

     <interface>
       <name>fastethernet-1/0</name>
       <type>ethernetCsmacd</type>
       <location>1/0</location>
     </interface>

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

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

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

Bjorklund                 Expires May 19, 2013                 [Page 32]
Internet-Draft          YANG Interface Management          November 2012

E.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- or
   gigabit-ethernet ports.

   The implementation does not restrict the interface names.  This
   allows to more easily apply the interface configuration to a
   different physical 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 "location" of
   an interface is a string on the form "N/M".

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

     <interface nc:operation="create">
       <name>acme-interface</name>
       <type>ethernetCsmacd</type>
       <location>1/0</location>
     </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>
       <location>2/4</location>
     </interface>

E.3.  Ethernet Switch with Restricted Interface Names

   In this example, an ethernet switch has a number of ports, each port
   identified by a simple port number.

   The implementation restricts the interface names to numbers that
   match the physical port number.

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

     <interface nc:operation="create">
       <name>6</name>
     </interface>

   When the server processes this request, it will set the leaf "type"

Bjorklund                 Expires May 19, 2013                 [Page 33]
Internet-Draft          YANG Interface Management          November 2012

   to "ethernetCsmacd" and "location" to "6".  Thus, if the client
   performs a <get-config> right after the <edit-config> above, it will
   get:

     <interface>
       <name>6</name>
       <type>ethernetCsmacd</type>
       <location>6</location>
     </interface>

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

     <interface nc:operation="merge">
       <name>6</name>
       <location>5</location>
     </interface>

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

E.4.  Generic Host with Restricted Interface Names

   In this example, a generic host has interfaces named by the kernel
   and without easily usable location information.  The system
   identifies the physical interface by the name assigned by the
   operating system to the interface.

   The implementation restricts the interface name to the operating
   system level name of the physical interface.

   An operator can configure a new 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 "ethernetCsmacd" and "location" to "eth8".  Thus, if the client
   performs a <get-config> right after the <edit-config> above, it will
   get:

     <interface>
       <name>eth8</name>
       <type>ethernetCsmacd</type>
       <location>eth8</location>
     </interface>

Bjorklund                 Expires May 19, 2013                 [Page 34]
Internet-Draft          YANG Interface Management          November 2012

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

     <interface nc:operation="merge">
       <name>eth8</name>
       <location>eth7</location>
     </interface>

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

E.5.  Generic Host with Arbitrary Interface Names

   In this example, a generic host has interfaces named by the kernel
   and without easily usable location information.  The system
   identifies the physical interface by the name assigned by the
   operating system to the interface.

   The implementation does not restrict the interface name to the
   operating system level name of the physical interface.  This allows
   to more easily apply the interface configuration to a different
   physical 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.

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

     <interface nc:operation="create">
       <name>acme-interface</name>
       <type>ethernetCsmacd</type>
       <location>eth4</location>
     </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>
       <location>eth3</location>
     </interface>

Bjorklund                 Expires May 19, 2013                 [Page 35]
Internet-Draft          YANG Interface Management          November 2012

Appendix F.  ChangeLog

   RFC Editor: remove this section upon publication as an RFC.

F.1.  Version -08

   o  Removed the mtu leaf.

   o  Added examples of different interface naming schemes.

F.2.  Version -07

   o  Made leaf speed config false.

F.3.  Version -06

   o  Added oper-status leaf.

   o  Added leaf-lists higher-layer-if and lower-layer-if, that show the
      interface layering.

   o  Added container statistics with counters.

F.4.  Version -05

   o  Added an Informative References section.

   o  Updated the Security Considerations section.

   o  Clarified the behavior of an NETCONF server when invalid values
      are received.

F.5.  Version -04

   o  Clarified why ifPromiscuousMode is not part of this data model.

   o  Added a table that shows the mapping between this YANG data model
      and IF-MIB.

F.6.  Version -03

   o  Added the section Relationship to the IF-MIB.

   o  Changed if-index to be a leaf instead of leaf-list.

   o  Explained the notation used in the data model tree picture.

Bjorklund                 Expires May 19, 2013                 [Page 36]
Internet-Draft          YANG Interface Management          November 2012

F.7.  Version -02

   o  Editorial fixes

F.8.  Version -01

   o  Changed leaf "if-admin-status" to leaf "enabled".

   o  Added Security Considerations

Bjorklund                 Expires May 19, 2013                 [Page 37]
Internet-Draft          YANG Interface Management          November 2012

Author's Address

   Martin Bjorklund
   Tail-f Systems

   Email: mbj@tail-f.com

Bjorklund                 Expires May 19, 2013                 [Page 38]