Guidance for Authors writing text for the BGP Tunnel Encapsulation Attribute

The BGP Tunnel Encapsulation Attribute (TEA) defines a BGP attribute that passes tunnel information. BGP passes this attribute to associate prefixes with a particular tunnel. Currently proposed BGP specifications in the IDR and BESS Working groups have defined new tunnels and new parameters for these tunnels in Sub-TLV. This document provides guidelines to help authors quickly write correct text for new tunnels (defined in tunnel TLVs) and new Sub-TLVs. These guidelines are given as "templates" to aid new authors. More experience authors should view these templates as a list of expected content. One additional challenge for tunnels defined by [RFC9012] TEA is the interaction with the PMSI tunnels (, ) is to carefully define the interaction between PMSI tunnels and TEA tunnels. This set of guidelines comes from the lessons learned from reviewing the following different drafts for the BGP TEA:

draft-ietf-idr-sr-policy-safi:: defines a BGP NLRI and a SR Policy tunnel TLV for the BGP TEA, and several Sub-TLVs for the SR Policy Tunnel TLV based on the SR Policy architecture .
IDR drafts defining parameters for the SR Policy tunnel:: This includes draft-ietf-idr-sr-policy-nrp, draft-idr-sr-policy-path-mtu, draft-ietf-idr-sr-policy-path-segment, and draft-ietf-sr-policy-seglist)
draft-ietf-idr-sdwan-edge-discovery:: defines a Hybrid SDWAN Tunnel and several Sub-TLVs.
draft-ietf-bess-multicast-controller:: defines two tunnels (Any Encapsulation tunnel (78), Load-Balancing Tunnel, Segment list Tunnel, and Sub-TLVs for these tunnels.
draft-ietf-bess-evpn-geneve:: defines a Geneve tunnel type, and a Geneve Tunnel Option Sub-TLV.

The purpose behind the guidelines is content rather than form. In the draft-ietf-idr-sdwan-discovery-document, I used tables to refer to Sub-TLVs supported and sections with the description. I will post prior to IETF-122 on the IDR wiki, reviews and suggested changes based on this document for the BESS and IDR draft using tunnels. This rought draft is to provides an snapshot of the Wiki prior to IETF-122.

This section describes a guideline for information regarding new tunnel types. It is presented as a template to aid new authors. Tunnel encapsulation specification requires the following things for each tunnel:

Name:: Short name that will go in IANA allocation
Code:: Code assigned by IANA
Description:: Give a description of the tunnel and usage. The authors should strive to have a paragraph of description, but the description may point to other sections in the document.
List of all Sub-TLVs supported:: This list should include the sub-TLV that may be sent in this tunnel TLV. This list should include mandatory and optional TLVs. Please denote which sub-TLVs are mandatory and which sub-TLVs are optional. Please note any sub-TLVs that are not listed are not supported.
List of all Sub-TLVs not supported:: This list includes the Sub-TLVs which are not supported by this tunnel TLV. Note that any Sub-TLVs which are not explicitly defined as supported are by default unsupported.
A validation procedure:: Each tunnel should have a set of procedures to determine if tunnel signaled by BGP is valid.
Multiple Tunnel interactions:: Multiple Tunnel TLVs can be included in a single BGP TEA. If there are interactions between Tunnel TLVs, then this should be described in this section. For example, if one Tunnel TLV defines a security association that another TLV uses.
Security Considerations:: A security section needs to provides specific comments regarding the information passed in the tunnel TLV. Tunnel TLVs can send critical information regarding a network infrastructure, and this critical information needs to be identified. After the critical information is identified, the security section should discuss how network operators should restrict access to such critical information.
Management Considerations:: A management section includes comments on how the tunnel will be managed.

It is helpful for items 1-5 be clearly laid out in one section.

1. Name:: Do: Give a short name Do not: Please do not replicate an existing tunnel or Sub-TLV name
2. Code:: Do: Use a TBDxx unless assigned a number by IANA. Do not: assign your own number for tunnel type.
3. Description:: Do: Do you give a short description regarding the tunnel, and link to a more extended text block giving a detailed description. Do not Forget: to give information in the longer text about conflicts with any other tunnels if both are attached to the same route, what network applications use the tunnel, and pros/cons about using tunnel.
4. List of all Sub-TLVs defined for this tunnel TLV: Do: Look at RFC9012 and any other TEA document you reference (e.g. draft-ietf-idr-sr-policy-safi). Do: Gather a full list of Sub-TLVs from IANA lists and put it in a table with an indication for mandatory, optional, or not-supported. Report any errors in the IANA list to the IDR chairs. Do: Provide a complete list with the form of name (code-number) for each item.
5. List of unsupported Sub-TLV:: This contains a list of Sub-TLVs which are not supported for this tunnel TLV
6. Validation procedure(s):: Do: Write up a validation procedure for each Tunnel. Do: Look at existing validation procedures in [RFC9012]. Validation procedures may or may not include The Tunnel-Egress Endpoint. Do Not Assume that one tunnel validation procedure matches another.
7. Multiple Tunnel Interactions: Do: Consider if this tunnel interacts with another tunnel specified for the prefixes (AFI/SAFI). If so, please give advice to the implementers. Do not: Forget to look at all existing Tunnel types at the IANA site (https://www.iana.org/assignments/bgp-tunnel-encapsulation/bgp-tunnel-encapsulation.xhtml).
8. Security Considerations:: Do: Please look draft-ietf-idr-sr-policy-safi for a good template. Do: Consider what information is critical information or mission-critical information in the tunnel TLV or sub-TLV passed in tunnel TLV. Do not: Forget to add the critical information in the security section.
9. Manageability section:: How is the operator going to create the new tunnels in configuration? This section consider how easy this tunnel is to manage or configure.

A document specifying a new Sub=TLV needs include the following Information:

1. Title:: Short title that goes in IANA documentation (10-15 characters).
2. Sub-TLV Type Code:: Value for Type code.
3. Encoding of Value bytes:: this information should include: 3.1 diagram of value byte 3.2 Description of each field in Encoding 3.3 Error handling per field
4. Tunnel TLVs this Sub-TLV can appear in:: The authors should list tunnel TLVs that support this Sub-TLV as mandatory or optional Sub-TLV
5. Sub-TLV role in validation:: Please indicate whether this Sub-TLV play a part in validation in the validation of the validation of any Tunnel TLV.

It is helpful for items 1-5 be clearly laid out in one section. If new sub-TLVs are defined, it is helpful that these Sub-TLVs go before the list of all sub-TLVs. In addition, the SUB-tLV may be part of discussions on: Multiple Tunnel interactions, security considerations with specific comments regarding critical information passed in a tunnel TLV in a BGP TEA, management considerations that includes comments on how the tunel will be managed.

1. Title:

One-line summary name that gets added to the IANA Sub-TLV list

2. Type:

Type code values (assigned by IANA) in the form value (IANA) or TBDnnn.

3. Encoding of value byte

3.1 diagram of byte layout:: Please use 32 bit layout.
3.2 Description of each field:: Each field should have title: definition: limits on the field: what values the field can take. If the field is variable give some indication of what the range or how it is calculated.
3.3 Error handling:: 1. Do: Specify what constitutes malformed Sub-TLV, and how a malformed Sub-TLV is process. RFC9012 specifies silently ignoring the Sub-TLV. 2. Do: Point to a description of content checking. If content checking is done in another process, still give a general hint on what that processing is. Do not: Hide the Sub-TLV error processing in an error handling section. Do: Provide an error handling section with an overall summary of error handling. Refer to this section, but provide the specific details for this Sub-TLV in this section.

4. Tunnel TLV this Sub-TLV can appear in

Do: Give a list on what existing Tunnel types this Sub-TLV can go in as a required or an optional Sub-TLV. Do: Give existing tunnel types tunnel types in RFCs and WG document. Optionally: Authors may list tunnel types in individual drafts. Do: Give the tunnel types by name and number.

5. Does this Sub-TLV play a part in validation

Please indicate whether this Sub-TLV is involved in the validation of the tunnel. Do: Indicate if multiple Sub-TLVs can be in the same tunnel TLV. Do: Indicate whether on the first Sub-TLV is processed or if all Sub-TLV is processed. Do: Consider cross-checking of Sub-TLVs within a Tunnel TLV and between two tunnel TLVs of the same type. Is there any restriction or cross checking?

5, Specific Security Considerations for this Sub-TLV:

If this Sub-TLV exposes critical information, how is it protected?

6. Specific Management issues regarding this Sub-TLV:

If this Sub-TLV exposes a name or an identifier (e.g. binding SID) that helps the management systems track something for provisioning or debugging, give hints on how this might be gathered or passed to management system. One example, is that the BGP-LS might gather this information in an SR routing system.

The Tunnel Encapsulation states that the consideration of "P-Multicast Service Interface Tunnel" (PMSI Tunnel) attribute are out of scope. Please fill out the PMSI and TEA template below. Review of these interactions took a long time in , so think carefully about these questions. Here's a few questions that must be answered in the Template: 1) When is the PMSI tunnel Attribute valid to attach by itself? 2) When is it valid to attach both the PMSI tunnel attribute and a BGP TEA? 2a) In the case that it is valid to attach both PMSI + TEA, what happens if either is malformed? 2b) In the case that it is required to attach both, what happens if either the PMSI or TEA is missing? Note: Malformed implies syntax checking. 2c) When it is invalid to attach both PMSI and TEA, what is the error procedure if both are attached? Is there content checking of the TEA that is impacted by PMSI? By content checking, this template document means that given valid TEA and PMSI attributes, some content checking must be done prior to installing the tunnel and/or a multicast tunnel.

This section specifies no IANA considerations

This document provides administrative guidelines for clearly specifying Tunnel Encapsulation [RFC9012} information in an Internet Draft or RFC. Since this is an administrative document, no security consideration are appropriate.