draft-ietf-pim-yang-12.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
    <!ENTITY pim-base-tree SYSTEM "ietf-pim-base.tree">
    <!ENTITY pim-base-yang SYSTEM "ietf-pim-base.yang">
    <!ENTITY pim-rp-tree SYSTEM "ietf-pim-rp.tree">
    <!ENTITY pim-rp-yang SYSTEM "ietf-pim-rp.yang">
    <!ENTITY pim-sm-tree SYSTEM "ietf-pim-sm.tree">
    <!ENTITY pim-sm-yang SYSTEM "ietf-pim-sm.yang">
    <!ENTITY pim-dm-tree SYSTEM "ietf-pim-dm.tree">
    <!ENTITY pim-dm-yang SYSTEM "ietf-pim-dm.yang">
    <!ENTITY pim-bidir-tree SYSTEM "ietf-pim-bidir.tree">
    <!ENTITY pim-bidir-yang SYSTEM "ietf-pim-bidir.yang">
]>

<!-- may be omitted for very short documents -->
<?rfc toc="yes"?>
<?rfc sortrefs="no"?>
<?rfc symrefs="yes"?>
<?rfc strict="no"?>
<?rfc rfcedstyle="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>

<!-- these two save paper: start new sections from the same page etc. -->
<?rfc compact="yes"?> <?rfc subcompact="no"?>

<!-- other categories: bcp, exp, historic, std -->
<rfc ipr="trust200902" category="std" docName="draft-ietf-pim-yang-12">

  <front>

    <title abbrev='PIM YANG'>
      A YANG data model for Protocol-Independent Multicast (PIM)
    </title>

    <author fullname="Xufeng Liu" initials="X." surname="Liu">
      <organization>Jabil</organization>
      <address>
        <postal>
          <street>8281 Greensboro Drive, Suite 200</street>
          <city>McLean</city>
          <code>VA 22102</code>
          <country>USA</country>
        </postal>
        <email>Xufeng_Liu@jabil.com</email>
      </address>
    </author>

    <author fullname="Pete McAllister" initials="P." surname="McAllister">
      <organization>Metaswitch Networks</organization>
      <address>
        <postal>
          <street>100 Church Street</street>
          <city>Enfield</city>
          <code>EN2 6BQ</code>
          <country>UK</country>
        </postal>
        <email> pete.mcallister@metaswitch.com</email>
      </address>
    </author>

    <author fullname="Anish Peter" initials="A." surname="Peter">
      <organization>Individual</organization>
      <address>
        <email>anish.ietf@gmail.com</email>
      </address>
    </author>

    <author fullname="Mahesh Sivakumar" initials="M." surname="Sivakumar">
      <organization>Cisco Systems</organization>
      <address>
        <postal>
        <street>510 McCarthy Boulevard</street>
        <city>Milpitas</city>
        <region>California</region>
        <country>USA</country>
        </postal>
        <email>masivaku@cisco.com</email>
      </address>
    </author>

    <author fullname="Yisong Liu" initials="Y." surname="Liu">
      <organization>Huawei Technologies</organization>
      <address>
        <postal>
        <street>Huawei Administration Building</street>
        <city>Longgang</city>
        <region>Guangdong</region>
        <code>518129</code>
        <country>China</country>
        </postal>
        <email>liuyisong@huawei.com</email>
      </address>
    </author>

    <author fullname="Fangwei Hu" initials="F." surname="Hu">
      <organization>ZTE Corporation</organization>
      <address>
        <postal>
        <street>889 Bibo Road</street>
        <city>Shanghai</city>
        <region>Shanghai</region>
        <code>201203</code>
        <country>China</country>
        </postal>
        <email>hu.fangwei@zte.com.cn</email>
      </address>
    </author>

    <date year="2017"/>
    <area>Routing</area>
    <workgroup>PIM Working Group</workgroup>

    <keyword>Network Management</keyword>
    <keyword>PIM</keyword>
    <keyword>YANG</keyword>

    <abstract>
      <t>
        This document defines a YANG data model that can be used to configure
        and manage Protocol Independent Multicast (PIM) devices. 
	The model covers the PIM protocol configuration,
	operational state, and event notifications data.
      </t>
    </abstract>
  </front>

  <middle>

<section title="Introduction">
  <t>
    YANG <xref target="RFC6020"/> <xref target="RFC7950"/> is a data
    definition language that was introduced to model the configuration
    and running state of a device managed using network management
    protocols such as NETCONF <xref target="RFC6241"/>.
    YANG is now also being used as a component of wider management
    interfaces, such as CLIs.
  </t>
  <t>
    This document defines a YANG data model that can be used to
    configure and manage Protocol-Independent Multicast (PIM) devices.
    This model supports the core PIM
    protocol, as well as many other features described in Section 2.1.
   Non-core features are defined as optional in the provided data model.
  </t>

  <section title="Terminology">
    <t>
      The terminology for describing YANG data models is found in
      <xref target="RFC6020"/> and <xref target="RFC7950"/>.
    </t>
    <t>
      A simplified graphical representation of the data model is used in
      this document.  The meaning of the symbols in these diagrams is
      defined in <xref target="I-D.ietf-netmod-yang-tree-diagrams"/>.
    </t>
    <t>
      The following abbreviations are used in this document and
      the defined model:
      <list style="hanging">
	<t hangText="ASM:"><vspace blankLines="0" />
	Any-Source Multicast service model
	<xref target="RFC3569"/> <xref target="RFC4607"/>.
	</t>
	
	<t hangText="BFD:"><vspace blankLines="0" />
	Bidirectional Forwarding Detection <xref target="RFC5880"/>.
	</t>
	
	<t hangText="BSR:"><vspace blankLines="0" />
	Bootstrap Router <xref target="RFC5059"/>.
	</t>
	
	<t hangText="DF:"><vspace blankLines="0" />
	Designated Forwarder <xref target="RFC5015"/>.
	</t>
     
	<t hangText="DR:"><vspace blankLines="0" />
	Designated Router <xref target="RFC7761"/>.
	</t>
	
	<t hangText="IGMP:"><vspace blankLines="0" />
	Internet Group Management Protocol <xref target="RFC3376"/>.
	</t>
	
	<t hangText="MLD:"><vspace blankLines="0" />
	Multicast Listener Discovery <xref target="RFC3810"/>.
	</t>
	
	<t hangText="MSDP:"><vspace blankLines="0" />
	Multicast Source Discovery Protocol <xref target="RFC3618"/>.
	</t>
     
	<t hangText="mLDP:"><vspace blankLines="0" />
	Multipoint extensions for LDP <xref target="RFC6388"/>.
	</t>
	
	<t hangText="MRIB:"><vspace blankLines="0" />
	Multicast Routing Information Base <xref target="RFC3973"/> 
	<xref target="RFC5015"/> <xref target="RFC7761"/>.
	</t>
	
	<t hangText="mVPN:"><vspace blankLines="0" />
	Multicast VPN.
	</t>
	
	<t hangText="PIM:"><vspace blankLines="0" />
	Protocol Independent Multicast. <xref target="RFC3973"/> 
	<xref target="RFC5015"/> <xref target="RFC7761"/>.
	</t>
     
	<t hangText="PIM-BIDIR:"><vspace blankLines="0" />
	Protocol Independent Multicast - Bidirectional Mode
	<xref target="RFC5015"/>.
	</t>
	
	<t hangText="PIM-DM:"><vspace blankLines="0" />
	Protocol Independent Multicast - Dense Mode
	<xref target="RFC3973"/>.
	</t>
	
	<t hangText="PIM-SM:"><vspace blankLines="0" />
	Protocol Independent Multicast - Sparse Mode
	<xref target="RFC7761"/>.
	</t>
	
	<t hangText="RP:"><vspace blankLines="0" />
	Rendezvous Point. <xref target="RFC7761"/>.
	</t>
	
	<t hangText="RPA:"><vspace blankLines="0" />
	Rendezvous Point Address. <xref target="RFC5015"/>.
	</t>
	
	<t hangText="RPF:"><vspace blankLines="0" />
	Reverse Path Forwarding. <xref target="RFC3973"/> 
	<xref target="RFC5015"/> <xref target="RFC7761"/>.
	</t>
     
	<t hangText="RPT:"><vspace blankLines="0" />
	Rendezvous-Point Tree. <xref target="RFC7761"/>.
	</t>
     
	<t hangText="SPT:"><vspace blankLines="0" />
	Shortest Path Tree. <xref target="RFC7761"/>.
	</t>
     
	<t hangText="SSM:"><vspace blankLines="0" />
	Source-Specific Multicast service model
	<xref target="RFC3569"/> <xref target="RFC4607"/>.
	</t>
	
	<t hangText="VRF:"><vspace blankLines="0" />
	Virtual Routing and Forwarding.
	</t>
      </list>
    </t>
  </section>

  <section title="Prefixes in Data Node Names">
    <t>
      In this document, names of data nodes, actions, and other data model
      objects are often used without a prefix, as long as it is clear from
      the context in which YANG module each name is defined.  Otherwise,
      names are prefixed using the standard prefix associated with the
      corresponding YANG module, as shown in Table 1.
    </t>

    <texttable anchor='table_prefixes' 
	       title="Prefixes and Corresponding YANG Modules">
      <ttcol>Prefix</ttcol>
      <ttcol>YANG module</ttcol>
      <ttcol>Reference</ttcol>
      <c>yang</c>
      <c>ietf-yang-types</c>
      <c><xref target="RFC6991"/></c>
      
      <c>inet</c>
      <c>ietf-inet-types</c>
      <c><xref target="RFC6991"/></c>
      
      <c>if</c>
      <c>ietf-interfaces</c>
      <c><xref target="I-D.ietf-netmod-rfc7223bis"/></c>
      
      <c>rt</c>
      <c>ietf-routing</c>
      <c><xref target="I-D.ietf-netmod-rfc8022bis"/></c>
      
      <c>rt-types</c>
      <c>ietf-routing-types</c>
      <c><xref target="I-D.ietf-rtgwg-routing-types"/></c>

      <c>bfd-types</c>
      <c>ietf-bfd-types</c>
      <c><xref target="I-D.ietf-bfd-yang"/></c>
    </texttable>
  </section>
</section>

    <section title="Design of Data Model">
      <section title="Scope of model">
        <t>
          The model covers PIM Sparse Mode <xref target="RFC7761"/>, including the
          Source-Specific subset <xref target="RFC3569"/> 
          <xref target="RFC4607"/>, Dense Mode
          <xref target="RFC3973"/>, and Bi-directional PIM <xref target="RFC5015"/>.
        </t>
        <t>
          The PIM extensions represented in the model include BSR
          <xref target="RFC5059"/> and Anycast-RP <xref target="RFC4610"/>.
        </t>
        <t>
	  The data model can be used to configure and manage these
	  protocol features. The operational state data and statistics
	  can be retrieved by this model. The protocol specific
	  notifications are also defined in the model.
        </t>
        <t>
          This model does not cover other multicast protocols such as IGMP/MLD,
          MSDP, mVPN, or mLDP in-band signalling. It does not cover
	  any configuration required to generate the MRIB. These will
	  be specified in separate documents.
        </t>
      </section>
      <section title="Optional capabilities">
        <t>
          This model is designed to represent the capabilities of PIM devices
          with various specifications, including some with basic subsets of the
          PIM protocol. The main design goals of this document are that any major
          now-existing implementation may be said to support the base model, and
          that the configuration of all implementations meeting the specification
          is easy to express through some combination of the features in the base
          model and simple vendor augmentations.
        </t>
        <t>
          There is also value in widely-supported features being standardized, to
          save work for individual vendors, and so that mapping between different
          vendors' configuration is not needlessly complicated. Therefore, these
          modules declare a number of features representing capabilities that
          not all deployed devices support.
        </t>
        <t>
          The extensive use of feature declarations should also substantially
          simplify the capability negotiation process for a vendor's PIM
          implementation.
        </t>
        <t>
          On the other hand, operational state parameters are not so widely
          designated as features, as there are many cases where the defaulting
          of an operational state parameter would not cause any harm to the
          system, and it is much more likely that an implementation without
          native support for a piece of operational state would be able to
          derive a suitable value for a state variable that is not natively
          supported.
        </t>
        <t>
          For the same reason, wide constant ranges (for example, timer maxima
          and minima) will be used in the model. It is expected that
	  vendors will augment the model with any specific extensions
	  and restrictions needed to adapt it to their vendor specific
	  implementation.  
        </t>
      </section>
      <section title="Datastore applicability">
	<t>
	  This model conforms to the Network Management Datastore
	  Architecture (NMDA) 
	  <xref target="I-D.ietf-netmod-revised-datastores"/>.
	  The operational state data is combined with the associated
	  configuration data in the same hierarchy
	  <xref target="I-D.ietf-netmod-rfc6087bis"/>.
	</t>
      </section>
      <section title="Top-level structure">
        <t>
          This model defines several separate modules for modelling PIM
          configuration, defined below. Again, this separation will make it
          easier to express the specific capabilities of a PIM device.
        </t>
        <t>
          The hierarchy of PIM configuration is designed so that objects that
          are only relevant for one situation or feature are collected in a
          container for that feature. For example, the configuration for PIM-SM
          that is not relevant for an SSM-only implementation is collected in an
          ASM container.
        </t>
        <t>
          Where fields are not genuinely essential to protocol operation, they
          are marked as optional. Some fields will be essential but have a
          default specified, so they need not be explicitly configured.
        </t>
        <t>
          This module structure also applies, where applicable, to the operational
          state and notifications of the model.
        </t>
      </section>
      <section title="Position of address family in hierarchy">
        <t>
          This document contains address-family as a node in the hierarchy
          multiple times: both under the interface list, and under the
	  PIM instance.
        </t>
        <t>
          The reasoning for this is to make it easier for implementations in which
          configuration options are not supported for specific address families.
        </t>
        <t>
          For these implementations, the restriction that interface configuration
          must be address-family independent may either be expressed as a vendor
          augmentation of an address-family-independent parameter above the
          address-family level, or by a constraint on the base model objects of a
          form similar to:
        </t>
        <figure><artwork>
must ". = ../../address-family[address-family='ipv4']/dr-priority" {
  error-app-tag "dr-priority-mismatch";
  error-message 
    "Error: IPv6 DR priority must match IPv4 DR priority.";
}
        </artwork></figure>
      </section>
    </section>

    <section title="Module Structure">
      <section title="PIM base module">
        <t>
          The PIM base module defines the router-wide configuration options not
          specific to any PIM mode, and is included by the other modules. There
          are a couple of things worth mentioning here regarding where the PIM
          model fits in the overall routing hierarchy 
	  <xref target="I-D.ietf-netmod-rfc8022bis"/>:
          <list style='numbers'>
            <t>
              This data model agrees to a routing-instance-centric (VRF)
              model view as opposed to protocol-centric mainly because it fits well into
              the routing-instance model, and it is easier to map from the VRF-centric
              to the protocol-centric than the other way around due to forward
              references.
            </t>
            <t>
              The PIM base model augments 
              "/rt:routing/rt:control-plane-protocols” as opposed to
	      augmenting 
	      "/rt:routing/rt:control-plane-protocols/rt:control-plane-protocol”,
	      as the 
              latter would allow multiple protocol instances per VRF,
	      while the PIM protocol is designed to be enabled or
	      disabled on the per VRF basis.
            </t>
          </list>
        </t>
        <figure><artwork>
&pim-base-tree;
        </artwork></figure>
      </section>
      <section title="PIM RP module">
        <t>
          The PIM RP module contains configuration information scoped to RPs or
          ranges of group addresses. This does not belong in the hierarchy
          under any PIM mode, but is augmented by the individual mode-specific
          modules as appropriate.
        </t>
        <figure><artwork>
&pim-rp-tree;
        </artwork></figure>
      </section>
      <section title="PIM-SM module">
        <t>
          This module covers Sparse Mode configuration, including PIM-ASM and PIM-SSM.
        </t>
        <figure><artwork>
&pim-sm-tree;
        </artwork></figure>
      </section>
      <section title="PIM-DM module">
        <t>
          This module will cover Dense Mode configuration.
        </t>
        <figure><artwork>
&pim-dm-tree;
        </artwork></figure>
      </section>
      <section title="PIM-BIDIR module">
        <t>
          This module will cover Bidirectional PIM configuration.
        </t>
        <figure><artwork>
&pim-bidir-tree;
        </artwork></figure>
      </section>
    </section>

    <section title="PIM YANG Modules">
      <section title="PIM base module">
        <figure><artwork>
          &pim-base-yang;
        </artwork></figure>
      </section>
      <section title="PIM RP module">
        <figure><artwork>
          &pim-rp-yang;
        </artwork></figure>
      </section>
      <section title="PIM-SM module">
        <figure><artwork>
          &pim-sm-yang;
        </artwork></figure>
      </section>
      <section title="PIM-DM module">
        <figure><artwork>
          &pim-dm-yang;
        </artwork></figure>
      </section>
      <section title="PIM-BIDIR module">
        <figure><artwork>
          &pim-bidir-yang;
        </artwork></figure>
      </section>
    </section>

    <section title="Implementation Status">
      <t>
	This section to be removed by the RFC editor.
      </t>

      <t>
	This section records the status of known implementations of the
	protocol defined by this specification at the time of posting of this
	Internet-Draft, and is based on a proposal described in <xref target="RFC7942"/>.
	The description of implementations in this section is intended to
	assist the IETF in its decision processes in progressing drafts to
	RFCs.  Please note that the listing of any individual implementation
	here does not imply endorsement by the IETF.  Furthermore, no effort
	has been spent to verify the information presented here that was
	supplied by IETF contributors.  This is not intended as, and must not
	be construed to be, a catalog of available implementations or their
	features.  Readers are advised to note that other implementations may
	exist.
      </t>

      <t>
	According to RFC 7942, "this will allow reviewers and working groups
	to assign due consideration to documents that have the benefit of
	running code, which may serve as evidence of valuable experimentation
	and feedback that have made the implemented protocols more mature.
	It is up to the individual working groups to use this information as
	they see fit".
      </t>

      <t>
	This document is the work result of the PIM working group's YANG multicast design
	team. The following wiki page contains the information on the 
	design team members, the meeting discussions, lists of modeled
	features, and which features are supported by which existing
	implementations:
      </t>
     
      <t>
	https://trac.ietf.org/trac/pim/wiki/yang
      </t>
    </section>

    <section title="Security Considerations">
      <t>
	Configuration and state data defined in this document are
	designed to be accessed via a management protocol with secure
	transport layer, such as NETCONF <xref target="RFC6241"/>. The NETCONF access
	control model <xref target="RFC6536"/> provides the 
	means to restrict access for specific users to a pre-
	configured subset of all available operations and contents.
      </t>
      <t>
	The models defined in this document contain a number of
	configuration data nodes that are writable, creatable, and
	deletable.
	Unauthorised access to the configuration data can adversely
	affect the routing subsystem of both the local device and the
	network.  This may lead to network malfunctions, delivery of
	packets to inappropriate destinations and other problems.
      </t>
    </section>

    <section title="IANA Considerations">
      <t>
        RFC Ed.: In this section, replace all occurrences of 'XXXX' with the
	actual RFC number (and remove this note).
      </t>
      <t>
	This document registers the following namespace URIs in the IETF XML
	registry <xref target="RFC3688"/>:
      </t>
      <figure><artwork>
--------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-pim-base
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-pim-bidir
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-pim-dm
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-pim-rp
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
URI: urn:ietf:params:xml:ns:yang:ietf-pim-sm
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
--------------------------------------------------------------------
      </artwork></figure>
      
      <t>
	This document registers the following YANG modules in the YANG Module
	Names registry <xref target="RFC6020"/>:
      </t>
      <figure><artwork>
--------------------------------------------------------------------
name:         ietf-pim-base
namespace:    urn:ietf:params:xml:ns:yang:ietf-pim-base
prefix:       pim-base
reference:    RFC XXXX
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
name:         ietf-pim-bidir
namespace:    urn:ietf:params:xml:ns:yang:ietf-pim-bidir
prefix:       pim-bidir
reference:    RFC XXXX
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
name:         ietf-pim-dm
namespace:    urn:ietf:params:xml:ns:yang:ietf-pim-dm
prefix:       pim-dm
reference:    RFC XXXX
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
name:         ietf-pim-rp
namespace:    urn:ietf:params:xml:ns:yang:ietf-pim-rp
prefix:       pim-rp
reference:    RFC XXXX
--------------------------------------------------------------------
      </artwork></figure>
      <figure><artwork>
--------------------------------------------------------------------
name:         ietf-pim-sm
namespace:    urn:ietf:params:xml:ns:yang:ietf-pim-sm
prefix:       pim-sm
reference:    RFC XXXX
--------------------------------------------------------------------
      </artwork></figure>
    </section>

    <section title='Acknowledgements'>
      <t>
        The authors would like to thank Steve Baillargeon, Guo Feng,
        Robert Kebler, Tanmoy Kundu, 
        and Stig Venaas for their valuable contributions.
      </t>
    </section>

  </middle>

  <back>

    <references title="Normative References">
      <?rfc include="reference.RFC.3569"?>
      <?rfc include="reference.RFC.3688"?>
      <?rfc include="reference.RFC.3973"?>
      <?rfc include="reference.RFC.4607"?>
      <?rfc include="reference.RFC.4610"?>
      <?rfc include="reference.RFC.5015"?>
      <?rfc include="reference.RFC.5059"?>
      <?rfc include="reference.RFC.6020"?>
      <?rfc include="reference.RFC.6991"?>
      <?rfc include="reference.RFC.7761"?>
      <?rfc include="reference.RFC.7950"?>
      <?rfc include="reference.I-D.ietf-netmod-revised-datastores.xml"?>
      <?rfc include="reference.I-D.ietf-netmod-rfc7223bis"?>
      <?rfc include="reference.I-D.ietf-netmod-rfc8022bis"?>
      <?rfc include="reference.I-D.ietf-rtgwg-routing-types.xml"?>
      <?rfc include="reference.I-D.ietf-bfd-yang.xml"?>
    </references>

    <references title="Informative References">
      <?rfc include="reference.RFC.3376"?>
      <?rfc include="reference.RFC.3618"?>
      <?rfc include="reference.RFC.3810"?>
      <?rfc include="reference.RFC.5880"?>
      <?rfc include="reference.RFC.6241"?>
      <?rfc include="reference.RFC.6388"?>
      <?rfc include="reference.RFC.6536"?>
      <?rfc include="reference.RFC.7942"?>
      <?rfc include="reference.I-D.ietf-netmod-rfc6087bis.xml"?>
      <?rfc include="reference.I-D.ietf-netmod-yang-tree-diagrams.xml"?>
    </references>

  </back>

</rfc>