Network Working Group M. Pels
Internet-Draft RIPE NCC
Intended status: Standards Track 16 February 2025
Expires: 20 August 2025
A YANG Data Model for BGP Communities
draft-ietf-grow-yang-bgp-communities-03
Abstract
This document defines a YANG data model for the structured
specification of BGP communities. The model provides operators with
a way to publish their locally defined BGP communities in a
standardized format.
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 20 August 2025.
Copyright Notice
Copyright (c) 2025 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. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Pels Expires 20 August 2025 [Page 1]
Internet-Draft BGP Community YANG February 2025
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Rationale . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Tree view . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 6
6. Data Elements . . . . . . . . . . . . . . . . . . . . . . . . 15
6.1. The "serial" leaf . . . . . . . . . . . . . . . . . . . . 15
6.2. The "uri" leaf . . . . . . . . . . . . . . . . . . . . . 15
6.3. The "description" leaf . . . . . . . . . . . . . . . . . 15
6.4. The "contact-url" leaf . . . . . . . . . . . . . . . . . 15
6.5. The "contact" list . . . . . . . . . . . . . . . . . . . 15
6.5.1. The "email-address" leaf . . . . . . . . . . . . . . 16
6.5.2. The "name" leaf . . . . . . . . . . . . . . . . . . . 16
6.5.3. The "role" leaf . . . . . . . . . . . . . . . . . . . 16
6.5.4. The "organization" leaf . . . . . . . . . . . . . . . 16
6.5.5. The "organizational-unit" leaf . . . . . . . . . . . 16
6.6. The "regular" list . . . . . . . . . . . . . . . . . . . 16
6.6.1. The "name" leaf . . . . . . . . . . . . . . . . . . . 16
6.6.2. The "category" leaf . . . . . . . . . . . . . . . . . 16
6.6.3. The "description" leaf . . . . . . . . . . . . . . . 17
6.6.4. The "global-admin" leaf . . . . . . . . . . . . . . . 17
6.6.5. The "local-admin" container . . . . . . . . . . . . . 17
6.7. The "extended" list . . . . . . . . . . . . . . . . . . . 18
6.7.1. The "name" leaf . . . . . . . . . . . . . . . . . . . 18
6.7.2. The "category" leaf . . . . . . . . . . . . . . . . . 18
6.7.3. The "description" leaf . . . . . . . . . . . . . . . 19
6.7.4. The "type" leaf . . . . . . . . . . . . . . . . . . . 19
6.7.5. The "subtype" leaf . . . . . . . . . . . . . . . . . 19
6.7.6. The "asn" leaf . . . . . . . . . . . . . . . . . . . 19
6.7.7. The "asn4" leaf . . . . . . . . . . . . . . . . . . . 19
6.7.8. The "local-admin" container . . . . . . . . . . . . . 19
6.8. The "large" list . . . . . . . . . . . . . . . . . . . . 20
6.8.1. The "name" leaf . . . . . . . . . . . . . . . . . . . 20
6.8.2. The "category" leaf . . . . . . . . . . . . . . . . . 20
6.8.3. The "description" leaf . . . . . . . . . . . . . . . 20
6.8.4. The "global-admin" leaf . . . . . . . . . . . . . . . 21
6.8.5. The "local-datapart-1" container . . . . . . . . . . 21
6.8.6. The "local-data-part-2" container . . . . . . . . . . 21
7. Type definitions . . . . . . . . . . . . . . . . . . . . . . 22
7.1. The "two-octet-as-number" data type . . . . . . . . . . . 22
7.2. The "community-name" data type . . . . . . . . . . . . . 22
7.3. The "community-category" data type . . . . . . . . . . . 22
7.4. The "community-description" data type . . . . . . . . . . 22
7.5. The "local-admin-format" data type . . . . . . . . . . . 22
7.6. The "field-name" data type . . . . . . . . . . . . . . . 22
7.7. The "field-pattern" data type . . . . . . . . . . . . . . 23
Pels Expires 20 August 2025 [Page 2]
Internet-Draft BGP Community YANG February 2025
7.8. The "field-description" data type . . . . . . . . . . . . 23
8. Operational guidelines . . . . . . . . . . . . . . . . . . . 23
8.1. Publishing guidelines . . . . . . . . . . . . . . . . . . 23
8.2. Parsing guidelines . . . . . . . . . . . . . . . . . . . 23
9. IANA considerations . . . . . . . . . . . . . . . . . . . . . 24
9.1. YANG Namespace Registration . . . . . . . . . . . . . . . 24
9.2. YANG Module Registration . . . . . . . . . . . . . . . . 24
9.3. YANG SID Allocation . . . . . . . . . . . . . . . . . . . 24
10. Implementation status . . . . . . . . . . . . . . . . . . . . 24
10.1. Publishing implementations . . . . . . . . . . . . . . . 25
10.2. Parser implementations . . . . . . . . . . . . . . . . . 25
11. Security considerations . . . . . . . . . . . . . . . . . . . 26
12. Normative References . . . . . . . . . . . . . . . . . . . . 26
13. Informative References . . . . . . . . . . . . . . . . . . . 27
Appendix A. JSON Examples . . . . . . . . . . . . . . . . . . . 28
A.1. RFC8195 Selective NO_EXPORT definition . . . . . . . . . 28
A.2. RFC4384 Data Collection definition . . . . . . . . . . . 29
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction
ISPs use BGP communities to add information to their 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[RFC1997],
Extended BGP communities[RFC4360] and Large BGP communities[RFC8092].
ISPs can use this standardized format to publish their community
definitions. Section 3 elaborates on further advantages of using
such a standardized format.
2. 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.
The meaning of the symbols in tree diagrams are defined in [RFC8340].
Pels Expires 20 August 2025 [Page 3]
Internet-Draft BGP Community YANG February 2025
3. Rationale
ISPs may define various BGP communities that have local significance
within 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 the AS with ASN 64501 is
originating a prefix from a point of presence in The Netherlands (ISO
3166-1 code 528). Communities could be used to allow customers of an
ISP to control the 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 whether and
where an ISP publishes community information. The lack of a well-
defined structure makes it hard to create a standardized publishing
mechanism, and to develop tools for automatically parsing community
information and eventually triggering configuration actions.
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 achieved
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.
This document only describes a data model for the publishing format
of community definitions. The publishing location and publishing
mechanism used are outside the scope of this specification. The data
model does not make any assumption about the protocol used to
publish/retrieve formatted data following the model.
4. Tree view
The following tree diagram provides an overview of the "ietf-grow-
yang-bgp-communities" data model.
Pels Expires 20 August 2025 [Page 4]
Internet-Draft BGP Community YANG February 2025
module: ietf-grow-yang-bgp-communities
+--rw bgp-communities
+--rw serial? uint32
+--rw uri? inet:uri
+--rw description? string
+--rw contact-url? inet:uri
+--rw contact* [email-address]
| +--rw email-address inet:email-address
| +--rw name? string
| +--rw role? string
| +--rw organization? string
| +--rw organizational-unit? string
+--rw regular* [name]
| +--rw name community-name
| +--rw category? community-category
| +--rw description? community-description
| +--rw global-admin two-octet-as-number
| +--rw local-admin
| +--rw format? local-admin-format
| +--rw field* [name]
| +--rw name field-name
| +--rw length? uint8
| +--rw pattern field-pattern
| +--rw description? field-description
+--rw extended* [name]
| +--rw name community-name
| +--rw category? community-category
| +--rw description? community-description
| +--rw type uint8
| +--rw subtype uint8
| +--rw (global-admin)
| | +--:(asn)
| | | +--rw asn? two-octet-as-number
| | +--:(asn4)
| | +--rw asn4? inet:as-number
| +--rw local-admin
| +--rw format? local-admin-format
| +--rw field* [name]
| +--rw name field-name
| +--rw length? uint8
| +--rw pattern field-pattern
| +--rw description? field-description
+--rw large* [name]
+--rw name community-name
+--rw category? community-category
+--rw description? community-description
+--rw global-admin inet:as-number
+--rw local-data-part-1
Pels Expires 20 August 2025 [Page 5]
Internet-Draft BGP Community YANG February 2025
| +--rw format? local-admin-format
| +--rw field* [name]
| +--rw name field-name
| +--rw length? uint8
| +--rw pattern field-pattern
| +--rw description? field-description
+--rw local-data-part-2
+--rw format? local-admin-format
+--rw field* [name]
+--rw name field-name
+--rw length? uint8
+--rw pattern field-pattern
+--rw description? field-description
5. YANG Module
This section contains the complete YANG module defined in this
document. A break-down of the individual elements in this module can
be found in Section 6.
<CODE BEGINS> file "ietf-grow-yang-bgp-communities@2025-02-13.yang"
module ietf-grow-yang-bgp-communities {
yang-version 1.1;
namespace
"urn:ietf:params:xml:ns:yang:ietf-grow-yang-bgp-communities";
prefix bgp-comm;
import ietf-inet-types {
prefix inet;
reference
"draft-ietf-netmod-rfc6991-bis-17: Common YANG Data Types";
}
organization
"IETF GROW Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/grow/>
WG List: <mailto:grow@ietf.org>
Author: Martin Pels
<mailto:mpels@ripe.net>";
description
"This module describes a structure for BGP Communities
Copyright (c) 2025 IETF Trust and the persons identified as
authors of the code. All rights reserved.
Pels Expires 20 August 2025 [Page 6]
Internet-Draft BGP Community YANG February 2025
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject to
the license terms contained in, the Revised BSD License set
forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC YYYY; see
the RFC itself for full legal notices.
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 (RFC 2119) (RFC 8174) when, and only when,
they appear in all capitals, as shown here.";
// RFC-EDITOR: please update YYYY with this RFC ID
revision 2025-02-13 {
description
"Initial revision.";
reference
"RFC YYYY: YANG Module for BGP Communities
RFC-EDITOR: please update YYYY with this RFC ID";
}
typedef two-octet-as-number {
type uint16;
description
"This type represents autonomous system numbers, which
identify an Autonomous System (AS).
Autonomous system numbers were originally limited to 16
bits. BGP extensions have enlarged the autonomous system
number space to 32 bits. The two-octet-as-number type uses
an uint16 base type for use cases where the enlarged number
space is not supported.";
reference
"RFC 1930: Guidelines for creation, selection, and
registration of an Autonomous System (AS)";
}
typedef community-name {
type string {
length "1..255";
pattern '[^ \t\r\n\p{C}]+';
}
description
Pels Expires 20 August 2025 [Page 7]
Internet-Draft BGP Community YANG February 2025
"This type restricts values for the name of a BGP community.";
}
typedef community-category {
type enumeration {
enum informational {
value 0;
description
"Informational community";
}
enum action {
value 1;
description
"Action community";
}
}
description
"This type restricts values for the category of a BGP
community.";
}
typedef community-description {
type string {
length "1..65535";
pattern '[^\p{C}]+';
}
description
"This type restricts values for the description of a BGP
community.";
}
typedef local-admin-format {
type enumeration {
enum decimal {
value 0;
description
"Decimal number string";
}
enum binary {
value 1;
description
"Bit string";
}
}
description
"This type defines the format options for a BGP community
Local Administrator/Local Data field encoding";
}
Pels Expires 20 August 2025 [Page 8]
Internet-Draft BGP Community YANG February 2025
typedef field-name {
type string {
length "1..255";
pattern '[^ \t\r\n\p{C}]+';
}
description
"This type restricts values for the name leaf of a BGP
community Local Administrator/Local Data field.";
}
typedef field-pattern {
type string {
length "1..4095";
pattern '[-0-9.,*?^$+|(){}\[\]]+';
}
description
"This type restricts values for the pattern leaf of a BGP
community Local Administrator/Local Data field. Patterns
are described as POSIX Extended Regular Expressions";
reference
"IEEE 1003.2-1992: Information Technology - Portable
Operating System Interface (POSIX) - Part 2: Shell and
Utilities (Vol. 1)";
}
typedef field-description {
type string {
length "1..65535";
pattern '[^\p{C}]+';
}
description
"This type restricts values for the description leaf of a BGP
community Local Administrator/Local Data field.";
}
grouping local-admin-fields {
description
"A group of subfields inside the Local Administrator/Local
Data section of a BGP Community";
list field {
key "name";
ordered-by user;
description
"Ordered list of fields with their meanings";
leaf name {
type field-name;
description
"The name of the field";
Pels Expires 20 August 2025 [Page 9]
Internet-Draft BGP Community YANG February 2025
}
leaf length {
type uint8;
description
"Length of the field";
}
leaf pattern {
type field-pattern;
mandatory true;
description
"Regular Expression describing the expected contents of
the field";
}
leaf description {
type field-description;
description
"A text description of the field contents";
}
}
}
container bgp-communities {
description
"A community set";
leaf serial {
type uint32;
must "boolean(.)";
description
"Version number of the community set";
}
leaf uri {
type inet:uri;
description
"Publication point for the community set";
}
leaf description {
type string {
length "1..65535";
pattern '[^\p{C}]+';
}
description
"A description for the community set";
}
leaf contact-url {
type inet:uri;
description
"A reference to a webpage with maintainer contact
information";
Pels Expires 20 August 2025 [Page 10]
Internet-Draft BGP Community YANG February 2025
}
list contact {
key "email-address";
description
"A list of contacts for the community set maintainer(s)";
leaf email-address {
type inet:email-address;
description
"Maintainer contact e-mail address";
}
leaf name {
type string {
length "1..255";
pattern '[^\p{C}]+';
}
description
"Maintainer contact name";
}
leaf role {
type string {
length "1..255";
pattern '[^\p{C}]+';
}
description
"Maintainer contact role";
}
leaf organization {
type string {
length "1..255";
pattern '[^\p{C}]+';
}
description
"Maintainer contact organization";
}
leaf organizational-unit {
type string {
length "1..255";
pattern '[^\p{C}]+';
}
description
"Maintainer contact organizational unit";
}
}
list regular {
key "name";
description
"A list of objects describing RFC 1997 BGP Communities";
leaf name {
Pels Expires 20 August 2025 [Page 11]
Internet-Draft BGP Community YANG February 2025
type community-name;
description
"Community name";
}
leaf category {
type community-category;
description
"Category of the community";
}
leaf description {
type community-description;
description
"Description for the community";
}
leaf global-admin {
type two-octet-as-number;
mandatory true;
description
"Global Administrator field";
}
container local-admin {
description
"Local Administrator Field";
leaf format {
type local-admin-format;
default "decimal";
description
"Format used for parsing Local Administrator subfields";
}
uses local-admin-fields;
}
reference
"RFC 1997: BGP Communities Attribute";
}
list extended {
key "name";
description
"A list of objects describing RFC 4360 Extended BGP
Communities";
leaf name {
type community-name;
description
"Community name";
}
leaf category {
type community-category;
description
"Category of the community";
Pels Expires 20 August 2025 [Page 12]
Internet-Draft BGP Community YANG February 2025
}
leaf description {
type community-description;
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 global-admin {
mandatory true;
description
"Global Administrator Field";
case asn {
leaf asn {
type two-octet-as-number;
must "../type = 0 or ../type = 64";
description
"Two-Octet AS";
}
}
case asn4 {
leaf asn4 {
type inet:as-number;
must "../type = 2 or ../type = 66";
description
"Four-Octet AS";
}
}
}
container local-admin {
description
"Local Administrator Field";
leaf format {
type local-admin-format;
default "decimal";
description
"Format used for parsing Local Administrator subfields";
}
Pels Expires 20 August 2025 [Page 13]
Internet-Draft BGP Community YANG February 2025
uses local-admin-fields;
}
reference
"RFC 4360: BGP Extended Communities Attribute";
}
list large {
key "name";
description
"A list of objects describing RFC 8092 Large BGP
Communities";
leaf name {
type community-name;
description
"Community name";
}
leaf category {
type community-category;
description
"Category of the community";
}
leaf description {
type community-description;
description
"Description for the community";
}
leaf global-admin {
type inet:as-number;
mandatory true;
description
"Global Administrator field";
}
container local-data-part-1 {
description
"Local Data Part 1 Field";
leaf format {
type local-admin-format;
default "decimal";
description
"Format used for parsing Local Data Part 1 subfields";
}
uses local-admin-fields;
}
container local-data-part-2 {
description
"Local Data Part 2 Field";
leaf format {
type local-admin-format;
default "decimal";
Pels Expires 20 August 2025 [Page 14]
Internet-Draft BGP Community YANG February 2025
description
"Format used for parsing Local Data Part 2 subfields";
}
uses local-admin-fields;
}
reference
"RFC 8092: BGP Large Communities Attribute";
}
}
}
<CODE ENDS>
6. Data Elements
The BGP Communities YANG module contains the elements described in
this section. The full contents of the module can be found in
Section 5. Several elements in this module use data types from
[I-D.ietf-netmod-rfc6991-bis]. These data types are represented with
the prefix "inet".
6.1. The "serial" leaf
A required value of type "uint32", containing the version number for
the community set. This value wraps and should be compared using
sequence space arithmetic. Publishing Implementations are free to
decide how to generate this value. One example method is to use the
YYYYMMDDnn syntax as commonly used inside the DNS[RFC1912].
6.2. The "uri" leaf
An optional value of type "inet:uri", describing the publication
point for the community set.
6.3. The "description" leaf
An optional value of type "string" with a maximum length of 65535,
providing information about the specified set of communities.
6.4. The "contact-url" leaf
An optional value of type "inet:uri", describing a webpage where
maintainer contact information may be found.
6.5. The "contact" list
A list of objects defining contact information for the maintainer(s)
of the community set. Each object contains the following elements.
Pels Expires 20 August 2025 [Page 15]
Internet-Draft BGP Community YANG February 2025
6.5.1. The "email-address" leaf
A required value of type "inet:email-address", containing the e-mail
address of the contact.
6.5.2. The "name" leaf
An optional value of type "string" with a maximum length of 255,
containing the name of the contact.
6.5.3. The "role" leaf
An optional value of type "string" with a maximum length of 255,
describing the role of the contact.
6.5.4. The "organization" leaf
An optional value of type "string" with a maximum length of 255,
containing the organization of the contact.
6.5.5. The "organizational-unit" leaf
An optional value of type "string" with a maximum length of 255,
containing the organizational unit of the contact.
6.6. The "regular" list
A list of objects defining Regular ([RFC1997]) BGP communities. Each
object contains the following elements.
6.6.1. The "name" leaf
A required value of type "community-name", containing the name of
this community.
The structure of the "community-name" type is defined in Section 7.2.
6.6.2. The "category" leaf
An optional value of type "community-category", containing the
category of this community.
The structure of the "community-category" type is defined in
Section 7.3.
Pels Expires 20 August 2025 [Page 16]
Internet-Draft BGP Community YANG February 2025
6.6.3. The "description" leaf
An optional value of type "community-description", containing a
description of this community.
The structure of the "community-description" type is defined in
Section 7.4.
6.6.4. The "global-admin" leaf
A required value of type "two-octet-as-number", containing the
Autonomous System Number (ASN) set in the Global Administrator part
of this community.
The structure of the "two-octet-as-number" type is defined in
Section 7.1.
6.6.5. The "local-admin" container
A group of elements that describe the Local Administrator part of the
community. This object contains the following elements.
6.6.5.1. The "format" leaf
An optional value of type "local-admin-format", describing the
encoding format in which fields are to be parsed (see Section 8.2).
The structure of the "local-admin-format" type is defined in
Section 7.5. If this leaf is not defined, the default "decimal"
encoding is assumed.
6.6.5.2. The "field" list
A list of objects that together form the Local Administrator part of
the community. The combined length values of all fields MUST NOT
exceed the maximum length of the Local Administrator part of the
community.
6.6.5.2.1. The "name" leaf
A required value of type "field-name", containing the name of the
field.
The structure of the "field-name" type is defined in Section 7.6.
Pels Expires 20 August 2025 [Page 17]
Internet-Draft BGP Community YANG February 2025
6.6.5.2.2. The "length" leaf
An optional value of type "uint8", containing the length of the
field. If the expected field format (Section 6.6.5.1) is "decimal",
this is a number of digits. In case the expected field format is
"binary", this is a number of bits.
Parsers use the field length to determine how many decimals or bits
from the Local Administrator part of the community are used by this
field. If this leaf is not defined, the length is assumed to be the
maximum allowed length of the entire field list. In this case the
field list MUST NOT contain more than one element.
6.6.5.2.3. The "pattern" leaf
A required value of type "field-pattern", used by parsers to match
the content of the corresponding field in the Local Administrator
part of a community. This could be a single value or a regular
expression pattern matching multiple values.
The structure of the "field-pattern" type is defined in Section 7.7.
6.6.5.2.4. The "description" leaf
An optional value of type "field-description", containing a
description of the pattern. This description can be used to provide
meaning to specific values for a field.
The structure of the "field-description" type is defined in
Section 7.8.
6.7. The "extended" list
A list of objects defining Extended ([RFC4360]) BGP communities.
Two-Octet and Four-Octet AS Specific communities are supported by
this specification. Each object contains the following elements.
6.7.1. The "name" leaf
A required value of type "community-name", containing the name of
this community.
The structure of the "community-name" type is defined in Section 7.2.
6.7.2. The "category" leaf
An optional value of type "community-category", containing the
category of this community.
Pels Expires 20 August 2025 [Page 18]
Internet-Draft BGP Community YANG February 2025
The structure of the "community-category" type is defined in
Section 7.3.
6.7.3. The "description" leaf
An optional value of type "community-description", containing a
description of this community.
The structure of the "community-description" type is defined in
Section 7.4.
6.7.4. The "type" leaf
A required value of type "uint8", containing the high-order Type of
the community. Supported values are 0 (0x00) for Transitive Two-
Octet AS-Specific Extended Communities, 2 (0x02) for Transitive Four-
Octet AS-Specific Extended Communities, 64 (0x40) for Non-Transitive
Two-Octet AS-Specific Extended Communities and 66 (0x42) for Non-
Transitive Four-Octet AS-Specific Extended Communities.
6.7.5. The "subtype" leaf
A required value of type "uint8", containing the low-order Sub-Type
of the community.
6.7.6. The "asn" leaf
For Two-Octet AS Specific communities: A required value of type "two-
octet-as-number", containing the Autonomous Sytem Number set in the
Global Administrator part of this community.
The structure of the "two-octet-as-number" type is defined in
Section 7.1.
6.7.7. The "asn4" leaf
For Four-Octet AS Specific communities: A required value of type
"inet:as-number", containing the ASN set in the Global Administrator
part of this community.
6.7.8. The "local-admin" container
A group of elements that describe the Local Administrator part of the
community. This object contains the following elements.
Pels Expires 20 August 2025 [Page 19]
Internet-Draft BGP Community YANG February 2025
6.7.8.1. The "format" leaf
An optional value of type "local-admin-format", describing the
encoding format in which fields are to be parsed (see Section 8.2).
The structure of the "local-admin-format" type is defined in
Section 7.5. If this leaf is not defined, the default "decimal"
encoding is assumed.
6.7.8.2. The "field" list
A list of objects that together form the Local Administrator part of
the community. The combined length values of all fields MUST NOT
exceed the maximum length of the Local Administrator part of the
community.
The supported leafs in this list are identical to those described in
Section 6.6.5.2.
6.8. The "large" list
A list of objects defining Large ([RFC8092]) BGP communities. Each
object contains the following elements.
6.8.1. The "name" leaf
A required value of type "community-name", containing the name of
this community.
The structure of the "community-name" type is defined in Section 7.2.
6.8.2. The "category" leaf
An optional value of type "community-category", containing the
category of this community.
The structure of the "community-category" type is defined in
Section 7.3.
6.8.3. The "description" leaf
An optional value of type "community-description", containing a
description of this community.
The structure of the "community-description" type is defined in
Section 7.4.
Pels Expires 20 August 2025 [Page 20]
Internet-Draft BGP Community YANG February 2025
6.8.4. The "global-admin" leaf
A required value of type "inet:as-number", containing the ASN set in
the Global Administrator part of this community.
6.8.5. The "local-datapart-1" container
A group of elements that describe the Local Data Part 1 section of
the community. This object contains the following elements.
6.8.5.1. The "format" leaf
An optional value of type "local-admin-format", describing the
encoding format in which fields are to be parsed (see Section 8.2).
The structure of the "local-admin-format" type is defined in
Section 7.5. If this leaf is not defined, the default "decimal"
encoding is assumed.
6.8.5.2. The "field" list
A list of objects that together form the Local Data Part 1 section of
the community. The combined length values of all fields MUST NOT
exceed the maximum length of the "Local Data Part 1" section of the
community.
The supported leafs in this list are identical to those described in
Section 6.6.5.2.
6.8.6. The "local-data-part-2" container
A group of elements that describe the Local Data Part 2 section of
the community. This object contains the following elements.
6.8.6.1. The "format" leaf
An optional value of type "local-admin-format", describing the
encoding format in which fields are to be parsed (see Section 8.2).
The structure of the "local-admin-format" type is defined in
Section 7.5. If this leaf is not defined, the default "decimal"
encoding is assumed.
Pels Expires 20 August 2025 [Page 21]
Internet-Draft BGP Community YANG February 2025
6.8.6.2. The "field" list
A list of objects that together form the Local Data Part 2 section of
the community. The combined length values of all fields MUST NOT
exceed the maximum length of the "Local Data Part 2" section of the
community.
The supported leafs in this list are identical to those described in
Section 6.6.5.2.
7. Type definitions
Several of the elements defined in Section 6 use custom data types.
These data types are defined here.
7.1. The "two-octet-as-number" data type
A Two-Octet Autonomous System Number, as defined in [RFC1930].
7.2. The "community-name" data type
A string specifying the name of a BGP community. Names may be up to
255 characters long and MUST NOT contain spaces or tabs.
7.3. The "community-category" data type
An enum specifying the category of a BGP community. Possible
categories are "informational" and "action", as described in
[RFC8195].
7.4. The "community-description" data type
A string specifying the description of a BGP community. Descriptions
may be up to 65535 characters long.
7.5. The "local-admin-format" data type
An enum specifying the encoding for a Local Administrator/Local Data
field. Possible encodings are "decimal" for decimal numbers and
"binary" for bit strings.
7.6. The "field-name" data type
A string specifying the name of a BGP community Local Administrator/
Local Data field. Names may be up to 255 characters long and MUST
NOT contain spaces or tabs.
Pels Expires 20 August 2025 [Page 22]
Internet-Draft BGP Community YANG February 2025
7.7. The "field-pattern" data type
A string specifying the pattern of a BGP community Local
Administrator/Local Data field. Patterns may be up to 4095
characters long and are described as POSIX Extended Regular
Expressions (see [IEEE.1003-2.1992], Section 2.8.4).
7.8. The "field-description" data type
A string specifying the description of a BGP community Local
Administrator/Local Data field. Descriptions may be up to 65535
characters long.
8. Operational guidelines
8.1. Publishing guidelines
Operators SHOULD only publish BGP community definitions for networks
they control. This may include communities where the Global
Administrator field contains a private ASN, if this community has a
local meaning inside the network of the publisher.
When publishing community definitions with overlapping field
patterns, these definitions MUST be ordered from most to least
preferred. This ensures parsers can perform deterministic matching
(see Section 8.2). For example, a definition for a single community
"64500:123" needs to be specified before a definition that matches a
covering range of communities "64500:*".
8.2. Parsing guidelines
A published BGP community definition can be used by parsers to
display information about a received community. If a received
community matches multiple published community definitions, the first
matching definition in the published order takes precedence.
Parsers that use published community definitions from multiple
operators SHOULD NOT attempt to match received communities where the
Global Administrator field contains a private ASN, unless they have
some method to determine which published definition is the
authoritative one.
By default, communities are compared using the decimal representation
of the fields. If "format" for a Local Administrator or Local Data
Part is set to "binary", the fields in the received community are
converted to strings of zeros and ones before comparison.
Pels Expires 20 August 2025 [Page 23]
Internet-Draft BGP Community YANG February 2025
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. For example, a Regular BGP community definition with
format "decimal" containing a field of length 4 and a field of length
2 would be illegal, as the Local Administrator field has a maximum
length of 65535 (5 digits).
9. IANA considerations
9.1. YANG Namespace Registration
This document registers the following XML namespace URN in the "IETF
XML Registry", following the format defined in [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-grow-yang-bgp-communities
Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace.
9.2. YANG Module Registration
This document registers the following YANG module in the "YANG Module
Names" registry [RFC6020]:
Name: ietf-grow-yang-bgp-communities
Maintained by IANA? N
Namespace: urn:ietf:params:xml:ns:yang:ietf-grow-yang-bgpcommunities
Prefix: bgp-comm
Reference: RFC YYYY
RFC-EDITOR: please update YYYY with this RFC ID
9.3. YANG SID Allocation
This document registers the following entry in the "IETF YANG SID"
registry [RFC9595]:
SID range entry point: TBD
SID range size: 100
YANG module name: ietf-grow-yang-bgp-communities
Reference: RFC YYYY
RFC-EDITOR: please update YYYY with this RFC ID
10. Implementation status
RFC-EDITOR: Please remove this section and the accompanying
reference(s) before publication.
Pels Expires 20 August 2025 [Page 24]
Internet-Draft BGP Community YANG February 2025
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 [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.
According to [RFC7942], "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".
10.1. Publishing implementations
The following networks are known to publish BGP community definitions
according to this specification.
+========+==========================================+============+
| ASN | Publication URI | YANG model |
| | | revision |
+========+==========================================+============+
| 197000 | as197000.json (https://www- | 2024-06-15 |
| | static.ripe.net/dynamic/draft-ietf-grow- | |
| | yang-bgp-communities/as197000.json) | |
+--------+------------------------------------------+------------+
| 25152 | as25152.json (https://www- | 2024-06-15 |
| | static.ripe.net/dynamic/draft-ietf-grow- | |
| | yang-bgp-communities/as25152.json) | |
+--------+------------------------------------------+------------+
Table 1: Publishing implementations
10.2. Parser implementations
The following known parser implementations exist.
Pels Expires 20 August 2025 [Page 25]
Internet-Draft BGP Community YANG February 2025
+===============================================+============+
| Name | YANG model |
| | revision |
+===============================================+============+
| NLNOG Looking Glass | 2024-06-15 |
| (https://github.com/NLNOG/lg.ring.nlnog.net/) | |
+-----------------------------------------------+------------+
Table 2: Parser implementations
11. 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.
The "contact-url" element defined in Section 6.4 may contain a link
to an untrusted webpage. Parsers MAY opt to render the URL as plain
text rather than a clickable link, to prevent inadvertent exposure of
information by users of the rendered output.
Several elements of the "contact" list defined in Section 6.5 may
contain personal data covered by privacy-laws. Publishers MUST
ensure that the elements defined in Section 6.5.1 and Section 6.5.2
do not contain any privacy-sensitive information.
12. Normative References
[I-D.ietf-netmod-rfc6991-bis]
Schönwälder, J., "Common YANG Data Types", Work in
Progress, Internet-Draft, draft-ietf-netmod-rfc6991-bis-
17, 21 October 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-netmod-
rfc6991-bis-17>.
[RFC1930] Hawkinson, J. and T. Bates, "Guidelines for creation,
selection, and registration of an Autonomous System (AS)",
BCP 6, RFC 1930, DOI 10.17487/RFC1930, March 1996,
<https://www.rfc-editor.org/info/rfc1930>.
[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>.
Pels Expires 20 August 2025 [Page 26]
Internet-Draft BGP Community YANG February 2025
[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>.
[RFC9595] Veillette, M., Ed., Pelov, A., Ed., Petrov, I., Ed.,
Bormann, C., and M. Richardson, "YANG Schema Item
iDentifier (YANG SID)", RFC 9595, DOI 10.17487/RFC9595,
July 2024, <https://www.rfc-editor.org/info/rfc9595>.
13. 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.
[RFC1912] Barr, D., "Common DNS Operational and Configuration
Errors", RFC 1912, DOI 10.17487/RFC1912, February 1996,
<https://www.rfc-editor.org/info/rfc1912>.
[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>.
Pels Expires 20 August 2025 [Page 27]
Internet-Draft BGP Community YANG February 2025
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
[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>.
[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>.
[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. JSON Examples
This section shows example use cases for the YANG module defined in
this document, using JSON[RFC7951] encoding.
A.1. RFC8195 Selective NO_EXPORT definition
A JSON definition for the example Large BGP community described in
[RFC8195], section 4.1.1 looks as follows.
NOTE: '\' line wrapping per [RFC8792]
Pels Expires 20 August 2025 [Page 28]
Internet-Draft BGP Community YANG February 2025
{
"ietf-grow-yang-bgp-communities:bgp-communities": {
"serial": 2023080101,
"uri": "http://example.net/peering/communities",
"description": "BGP Community example for ASN-Based Selective \
NO_EXPORT",
"contact": [
{
"email-address": "noc@example.net",
"name": "Example.net contact",
"role": "Administrative contact",
"organization": "Example.net",
"organizational-unit": "NOC"
}
],
"large": [
{
"name": "RFC8195-NOEXPORT-ASN",
"category": "action",
"description": "Do not export route to ASN",
"global-admin": 65539,
"local-data-part-1": {
"field": [
{
"name": "Function",
"pattern": "4",
"description": "ASN-No-Export"
}
]
},
"local-data-part-2": {
"field": [
{
"name": "ASN",
"pattern": ".*"
}
]
}
}
]
}
}
A.2. RFC4384 Data Collection definition
A JSON definition for the example Regular BGP community described in
[RFC4384], section 4 looks as follows.
Pels Expires 20 August 2025 [Page 29]
Internet-Draft BGP Community YANG February 2025
NOTE: '\' line wrapping per [RFC8792]
{
"ietf-grow-yang-bgp-communities:bgp-communities": {
"serial": 2023080101,
"uri": "http://example.net/peering/communities",
"description": "BGP Community example for Data Collection",
"contact-url": "https://example.net/contact",
"regular": [
{
"name": "RFC4384-ORIGIN-OC/FJ",
"description": "A national route over a terrestrial link \
from the Fiji Islands",
"global-admin": 64497,
"local-admin": {
"format": "binary",
"field": [
{
"name": "Region",
"length": 5,
"pattern": "00010",
"description": "OC"
},
{
"name": "Satellite",
"length": 1,
"pattern": "0"
},
{
"name": "Country",
"length": 10,
"pattern": "0011110010",
"description": "FJ"
}
]
}
}
]
}
}
Appendix B. Acknowledgements
The author would like to thank Jeffrey Haas, Luuk Hendriks, Jasper
den Hertog, Teun Vink, Tom Petch, Dale Carder and Mohamed Boucadair
for contributing ideas and feedback to this document.
Pels Expires 20 August 2025 [Page 30]
Internet-Draft BGP Community YANG February 2025
Author's Address
Martin Pels
RIPE NCC
Netherlands
Email: mpels@ripe.net
Pels Expires 20 August 2025 [Page 31]