YANG Module for BGP Communities

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 8 May 2024.¶

Copyright Notice

Copyright (c) 2023 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. Terminology

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.¶

2. Introduction

ISP operators use BGP communities[RFC1997][RFC4360][RFC8092] to add information to prefix announcements or to let customers influence routing behaviour inside the network of the ISP. Each ISP defines for itself which BGP communities to support and how the structure of these communities should be interpreted. This document provides a YANG[RFC7950] module for describing the structure and meaning of BGP communities, Extended BGP communities and Large BGP communities. ISP operators can use this to publish their community definitions in a well-defined format.¶

3. Rationale

ISP operators may define various BGP communities that have local significance inside of their network. These communities could be used to add miscellaneous information to a prefix announcement. For example, a community "64501:1:528" may signify that AS64501 is originating a prefix from a point of presence in The Netherlands (ISO 3166-1 code 528). Alternatively, communities could be used to allow customers of an ISP to control routing behavior of their prefixes inside the ISP. For example, a community "64501:4:64498" attached to a prefix advertised to AS64501 by a customer may be interpreted by AS64501 to mean that this prefix must not be propagated to AS64498.¶

For both use cases it is necessary for the ISP to communicate the meaning of their locally defined communities to others. Currently this is typically done by publishing a list of communities on a web page, or as a remark inside an autnum object in the Internet Routing Registry. This makes it cumbersome to determine if and where an ISP publishes community information. The lack of a well-defined structure makes it hard to develop tools for parsing community information.¶

The purpose of the YANG model defined in this document is to provide a standardized format for publishing community definitions. These definitions help applications to interpret the structure and purpose of BGP communities. For example, looking glasses may use the published definitions to parse communities seen in BGP announcements and display their meaning. Another potential use case is in generating routing policy configurations based on community definitions published by an upstream ASN. This could be done automatically using external tooling to generate router configurations, or inside a router's command-line interface by importing the definitions and providing the CLI-user with available choices for manual configuration.¶

Note that this document only describes a model for the publishing format of community definitions. The publishing location and publishing mechanism used are outside the scope of this specification.¶

4. Tree view

The following tree diagram provides an overview of the ietf-bgp-communities.yang data model.¶

module: draft-pels-grow-yang-bgp-communities
  +--rw bgp-communities
     +--rw serial         uint32
     +--rw uri?           string
     +--rw description?   string
     +--rw contacturl?    string
     +--rw contacts* [emailaddress]
     |  +--rw emailaddress          string
     |  +--rw name?                 string
     |  +--rw role?                 string
     |  +--rw organization?         string
     |  +--rw organizationalunit?   string
     +--rw regular* [name]
     |  +--rw name           string
     |  +--rw description?   string
     |  +--rw globaladmin    uint16
     |  +--rw localadmin
     |     +--rw format?   string
     |     +--rw fields* [name]
     |        +--rw name           string
     |        +--rw length?        uint8
     |        +--rw pattern        string
     |        +--rw description?   string
     +--rw extended* [name]
     |  +--rw name             string
     |  +--rw description?     string
     |  +--rw type             uint8
     |  +--rw subtype          uint8
     |  +--rw (globaladmin)
     |  |  +--:(asn)
     |  |  |  +--rw asn?   uint16
     |  |  +--:(asn4)
     |  |     +--rw asn4?   uint32
     |  +--rw localadmin
     |     +--rw format?   string
     |     +--rw fields* [name]
     |        +--rw name           string
     |        +--rw length?        uint8
     |        +--rw pattern        string
     |        +--rw description?   string
     +--rw large* [name]
        +--rw name              string
        +--rw description?      string
        +--rw globaladmin       uint32
        +--rw localdatapart1
        |  +--rw format?   string
        |  +--rw fields* [name]
        |     +--rw name           string
        |     +--rw length?        uint8
        |     +--rw pattern        string
        |     +--rw description?   string
        +--rw localdatapart2
           +--rw format?   string
           +--rw fields* [name]
              +--rw name           string
              +--rw length?        uint8
              +--rw pattern        string
              +--rw description?   string

5. Data elements

The BGP Communities YANG Module contains the elements described in this section. The full contents of the module can be found in Appendix A.¶

6. Operational guidelines

7. IANA considerations

8. Security considerations

The YANG module described in this document may be used to specify BGP community definitions in different encoding formats, such as XML, JSON or CBOR. Applications that parse these community definitions SHOULD reject objects that do not comply with the rules described in this document. Furthermore, parsers SHOULD check that the sum of the specified Local Administrator or Local Data Part field lengths in each community definition does not exceed the local part size of the specified community type.¶

9. Normative References

[I-D.ietf-core-sid]

Veillette, M., Pelov, A., Petrov, I., Bormann, C., and M. Richardson, "YANG Schema Item iDentifier (YANG SID)", Work in Progress, Internet-Draft, draft-ietf-core-sid-20, 1 March 2023, <https://datatracker.ietf.org/doc/html/draft-ietf-core-sid-20>.

[RFC1997]

Chandra, R., Traina, P., and T. Li, "BGP Communities Attribute", RFC 1997, DOI 10.17487/RFC1997, August 1996, <https://www.rfc-editor.org/info/rfc1997>.

[RFC4360]

Sangli, S., Tappan, D., and Y. Rekhter, "BGP Extended Communities Attribute", RFC 4360, DOI 10.17487/RFC4360, February 2006, <https://www.rfc-editor.org/info/rfc4360>.

[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>.

[RFC8092]

Heitz, J., Ed., Snijders, J., Ed., Patel, K., Bagdonas, I., and N. Hilliard, "BGP Large Communities Attribute", RFC 8092, DOI 10.17487/RFC8092, February 2017, <https://www.rfc-editor.org/info/rfc8092>.

10. Informative References

[IEEE.1003-2.1992]

Institute of Electrical and Electronics Engineers, "Information Technology - Portable Operating System Interface (POSIX) - Part 2: Shell and Utilities (Vol. 1)", IEEE Standard 1003.2, IEEE 1003.2-1992, IEEE ieee-1003-2, 1992.

[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>.

[RFC3688]

Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.

[RFC4384]

Meyer, D., "BGP Communities for Data Collection", BCP 114, RFC 4384, DOI 10.17487/RFC4384, February 2006, <https://www.rfc-editor.org/info/rfc4384>.

[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>.

[RFC7951]

Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.

[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>.

[RFC8195]

Snijders, J., Heasley, J., and M. Schmidt, "Use of BGP Large Communities", RFC 8195, DOI 10.17487/RFC8195, June 2017, <https://www.rfc-editor.org/info/rfc8195>.

[RFC8792]

Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, "Handling Long Lines in Content of Internet-Drafts and RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020, <https://www.rfc-editor.org/info/rfc8792>.

Appendix A. YANG Module

This section contains the complete YANG module defined in this document.¶

NOTE: '\' line wrapping per [RFC8792]¶

module draft-pels-grow-yang-bgp-communities {

  yang-version 1.1;

  namespace "urn:to-be-defined";

  prefix bgpcomm;

  organization
    "To be defined";

  contact
    "To be defined";

  description
    "This module describes a structure for BGP Communities";

  revision "2023-08-01" {
    description
      "Initial version.";
    reference "0.0.2";
  }

  grouping localadmin-fields {
    list fields {
      ordered-by user;
      key "name";

      leaf name {
        type string {
          length "1..255";
          pattern "[^ \t\n]+";
        }
        mandatory "true";
        description
          "The name of the field";
      }

      leaf length {
        type uint8;
        description
          "Length of the field";
      }

      leaf pattern {
        type string;
        mandatory "true";
        description
          "Regular Expression describing the expected contents of the \
field";
      }

      leaf description {
        type string;
        description
          "A text description of the field contents";
      }
    }
  }

  container bgp-communities {

    leaf serial {
      type "uint32";
      mandatory "true";
      description
        "Version number of the community set.";
    }

    leaf uri {
      type string;
      description
        "Publication point for the community set";
    }

    leaf description {
      type string;
      description
        "A description for the community set";
    }

    leaf contacturl {
      type string;
      description
        "A reference to a webpage with maintainer contact information";
    }

    list contacts {
      key "emailaddress";

      leaf emailaddress {
        type string;
        description
          "Maintainer contact e-mail address";
      }

      leaf name {
        type string;
        description
          "Maintainer contact name";
      }

      leaf role {
        type string;
        description
          "Maintainer contact role";
      }

      leaf organization {
        type string;
        description
          "Maintainer contact organization";
      }

      leaf organizationalunit {
        type string;
        description
          "Maintainer contact organizational unit";
      }
    }

    list regular {
      key "name";

      leaf name {
        type string {
          length 1..255;
          pattern "[^ \t\n]+";
        }
        mandatory "true";
        description
          "Community name.";
      }

      leaf description {
        type string;
        description
          "Description for the community";
      }

      leaf globaladmin {
        type "uint16";
        mandatory "true";
        description
          "Global Administrator field";
      }

      container localadmin {
        leaf format {
          type "string" {
            pattern
              'decimal|binary';
          }
          default "decimal";
          description
            "Format used for parsing localadmin fields";
        }

        uses localadmin-fields;
      }
    }

    list extended {
      key "name";

      leaf name {
        type string {
          length 1..255;
          pattern "[^ \t\n]+";
        }
        mandatory "true";
        description
          "Community name";
      }

      leaf description {
        type string;
        description
          "Description for the community";
      }

      leaf type {
        type uint8;
        mandatory "true";
        description
          "Type Field";
      }
      leaf subtype {
        type uint8;
        mandatory "true";
        description
          "Sub-Type Field";
      }

      choice globaladmin {
        mandatory "true";
        case asn {
          leaf asn {
            type "uint16";
            description
              "Two-Octet AS";
          }
        }
        case asn4 {
          leaf asn4 {
            type "uint32";
            description
              "Four-Octet AS";
          }
        }
      }

      container localadmin {
        leaf format {
          type "string" {
            pattern
              'decimal|binary';
          }
          default "decimal";
          description
            "Format used for parsing localadmin fields";
        }

        uses localadmin-fields;
      }
    }

    list large {
      key "name";

      leaf name {
        type string {
          length 1..255;
          pattern "[^ \t\n]+";
        }
        mandatory "true";
        description
          "Community name.";
      }

      leaf description {
        type string;
        description
          "Description for the community";
      }

      leaf globaladmin {
        type "uint32";
        mandatory "true";
        description
          "Global Administrator field";
      }

      container localdatapart1 {
        leaf format {
          type "string" {
            pattern
              'decimal|binary';
          }
          default "decimal";
          description
            "Format used for parsing localadmin fields";
        }

        uses localadmin-fields;
      }

      container localdatapart2 {
        leaf format {
          type "string" {
            pattern
              'decimal|binary';
          }
          default "decimal";
          description
            "Format used for parsing localadmin fields";
        }

        uses localadmin-fields;
      }
    }
  }
}

Appendix B. JSON Examples

This section shows example use cases for the YANG module defined in this document, using JSON[RFC7951] encoding.¶

{
  "draft-pels-grow-yang-bgp-communities:bgp-communities": {
    "serial": 2023080101,
    "uri": "http://example.net/peering/communities",
    "description": "BGP Community example for ASN-Based Selective \
NO_EXPORT",
    "contacts": [
      {
        "emailaddress": "noc@example.net",
        "name": "Example.net contact",
        "role": "Administrative contact",
        "organization": "Example.net",
        "organizationalunit": "NOC"
      }
    ],
    "large": [
      {
        "name": "RFC8195-NOEXPORT-ASN",
        "description": "Do not export route to ASN",
        "globaladmin": 65539,
        "localdatapart1": {
          "fields": [
            {
              "name": "Function",
              "pattern": "4",
              "description": "ASN-No-Export"
            }
          ]
        },
        "localdatapart2": {
          "fields": [
            {
              "name": "ASN",
              "pattern": ".*"
            }
          ]
        }
      }
    ]
  }
}

{
  "draft-pels-grow-yang-bgp-communities:bgp-communities": {
    "serial": 2023080101,
    "uri": "http://example.net/peering/communities",
    "description": "BGP Community example for Data Collection",
    "contacturl": "https://example.net/contact",
    "regular": [
      {
        "name": "RFC4384-ORIGIN-OC/FJ",
        "description": "A national route over a terrestrial link from \
the Fiji Islands",
        "globaladmin": 64497,
        "localadmin": {
          "format": "binary",
          "fields": [
            {
              "name": "Region",
              "length": 5,
              "pattern": "00010",
              "description": "OC"
            },
            {
              "name": "Satellite",
              "length": 1,
              "pattern": "0"
            },
            {
              "name": "Country",
              "length": 10,
              "pattern": "0011110010",
              "description": "FJ"
            }
          ]
        }
      }
    ]
  }
}

Appendix C. Acknowledgements

The author would like to thank Jeffrey Haas, Luuk Hendriks, Jasper den Hertog and Teun Vink for contributing ideas and feedback to this document.¶

Author's Address