Internet-Draft YANG Unknown Bits April 2023
Haas Expires 12 October 2023 [Page]
Workgroup:
netmod
Internet-Draft:
draft-haas-netmod-unknown-bits-02
Published:
Intended Status:
Standards Track
Expires:
Author:
J. Haas
Juniper Networks

Representing Unknown YANG bits in Operational State

Abstract

Protocols frequently have fields where the contents are a series of bits that have specific meaning. When modeling operational state for such protocols in YANG, the 'bits' YANG built-in type is a natural method for modeling such fields. The YANG 'bits' built-in type is best suited when the meaning of a bit assignment is clear.

When bits that are currently RESERVED or otherwise unassigned by the protocol are received, being able to model them is necessary in YANG operational models. This cannot be done using the YANG 'bits' built-in type without assigning them a name. However, YANG versioning rules do not permit renaming of named bits.

This draft proposes a methodology to represent unknown bits in YANG operational models and creates a YANG typedef to assist in uniformly naming such unknown bits.

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 12 October 2023.

▲

Table of Contents

1. Requirements Language

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. Modeling Protocol Bit Vectors in YANG

Protocols frequently will have bit vectors as fields. Not all bits in such bit vectors are assigned during the specification of the protocol. These unassigned bits are typically made RESERVED and are used at a later date to provide for new features.

The YANG 'bits' built-in type (Section 9.7 of [RFC7950]) can be used to provide a "named bit" mapping to currently assigned bits in such fields. The representation format of 'bits' is "a space-separated list of the names of the bits that are set". However, when no assignment has been made for a bit position, nothing will be rendered.

There are operational needs for displaying received bits that may not be part of known assignments in the protocol. One such example is debugging behavior when unexpected bits have been sent in the protocol. This may occur when interacting with a version of the protocol that has assigned a previously unassigned bit.

One way to model such a scenario is to have one YANG leaf that covers known bit assignments, and have a subsequent YANG leaf contain unknown bits.

3. Modeling Unknown Bits

3.1. Example of Issue: Modeling BGP's Graceful Restart Flags

BGP's Graceful Restart Capability (Section 3 of [RFC4724]) contains a Restart Flags field that is four bits wide. Its definition is copied below:


 0 1 2 3
+-+-+-+-+
|R|Resv.|
+-+-+-+-+
Figure 1: BGP Graceful Restart Flags

The 'R' (Restart State) bit has been assigned in RFC 4724. One way to model this (taken from [I-D.ietf-idr-bgp-model]) is:


     typedef graceful-restart-flags {
       type bits {
         bit restart {
           position 0;
           description
             "The most significant bit is defined as the Restart
              State (R) bit, [...]";
           reference
             "RFC 4724: Graceful Restart Mechanism for BGP,
              Section 3.";
         }
       }
       [...]
     }

     [...]

     leaf flags {
       type bt:graceful-restart-flags;
       description
         "Restart Flags advertised by the Graceful Restart
          Capability";
       reference
         "RFC 4724: Graceful Restart Mechanism for BGP, Section 3.";
     }
Figure 2: BGP Graceful Restart Flags

[RFC8538] later assigns bit position 1 to the 'N' flag, updating the set of flags used in this field:


 0 1 2 3
+-+-+-+-+
|R|N|   |
+-+-+-+-+
Figure 3: BGP Graceful Restart Flags, Revised by RFC 8538

YANG module versioning rules would require the graceful-restart-flags typedef to be updated. For protocol well-known fields, this encourages such typedefs to be IANA-maintained for ease of update. A revised typedef may resemble:


     typedef graceful-restart-flags {
       type bits {
         bit restart {
           position 0;
           description
             "The most significant bit is defined as the Restart
              State (R) bit, [...]";
           reference
             "RFC 4724: Graceful Restart Mechanism for BGP,
              Section 3.";
         }
         bit notification {
           position 1;
           description
             "The second most significant bit is defined in [RFC 8538]
              as the Graceful Notification ('N') bit. [...]";
           reference
             "RFC 8538: Notification Message Support for BGP Graceful
              Restart, Section 2.";
         }
       }
     }
Figure 4: Revised BGP Graceful Restart Flags Typedef

Consider a router supporting the old typedef receiving a BGP Graceful Restart Capability containing both the 'R' and 'N' bits in the BGP protocol. In that typedef, the "flags" leaf could only represent position 0, the "restart" named bit. The implementation couldn't represent that the 'N' bit was sent in the protocol.


            <flags>restart</flags>
Figure 5: Flags for 'R' and 'N' bits with original leaves and typedef

3.2. Defining Unknown Bits

One solution to modeling unknown bits is to have a subsequent leaf whose purposes is only to model unknown bit mappings. When the protocol does not send the unassigned bits, this leaf would be absent in the output of the operational state.

Using the example where only the 'R' bit was defined, one way to model this would be:


     typedef  unknown-flags {
       type bits {
         bit bit-1 {
           position 1;
           description
             "Bit 1 was received but is currently RESERVED.";
         }
         bit bit-2 {
           position 2;
           description
             "Bit 2 was received but is currently RESERVED.";
         }
         bit bit-3 {
           position 3;
           description
             "Bit 3 was received but is currently RESERVED.";
         }
       }
       description
         "When a bit is exchanged in the Graceful Restart Flags
          field that is unknown to this module, their bit position
          is rendered using the associated unknown bit.";
       reference
         "RFC 4724: Graceful Restart Mechanism for BGP, Section 3.";
     }
     leaf unknown-flags {
       type unknown-flags;
       description
         "Restart Flags advertised by the Graceful Restart
          Capability";
       reference
         "RFC 4724: Graceful Restart Mechanism for BGP, Section 3.";
     }
Figure 6: BGP Graceful Restart Specific Unknown Bits

If the router using the above modeling received a BGP Graceful Restart Capability containing both the 'R' and the 'N' bits, it would now be rendered:


            <flags>restart</flags>
            <unknown-flags>bit-1</unknown-flags>
Figure 7: Flags for 'R' and 'N' bits with new leaves and typedefs

Deleting bit assignments in later versions of the model is not permitted by current YANG versioning rules. The only purpose of such unknown named bits is to represent fields that may later be assigned during maintenance of the protocol.

For example, when position 1, "bit notification" is assigned, the same example scenario would then render as:


            <flags>restart unknown</flags>
Figure 8: Flags for 'R' and 'N' bits with new leaves and updated typedef

3.3. Consistently Modeling Unknown Bits

Each YANG module requiring this pattern to represent unknown bits could define its own protocol-specific typedefs for the appropriate number of unknown bits for their fields. However, there is operational benefit to use a consistent pattern for such unknown bits. A common typedef for this purpose, "unknown-bits", is defined in the next section.

The unknown-bits typedef defines 64 bits of unknown bits. Considering the example for the BGP Graceful Restart Flags bits where only 4 bits are present in the field, 64 bits for the typedef are not a problem. Only the bits received in the protocol that aren't recognized would be represented in the protocol-specific "unknown-flags" leaf, or similar.

Here's an example usage of this typedef using the prior "unknown-flags" leaf:


     include ietf-yang-unknown-bit-types {
       prefix yang-ubt;
     }
     leaf unknown-flags {
       type ubt:unknown-bits;
       description
         "When a bit is exchanged in the Graceful Restart Flags
          field that is unknown to this module, their bit position
          is rendered using the associated unknown bit.";
       reference
         "RFC 4724: Graceful Restart Mechanism for BGP, Section 3.";
     }
Figure 9: BGP Graceful Restart Specific Unknown Bits with Typedef

4. IETF YANG Unknown Bit Types Module 


module ietf-yang-unknown-bit-types {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-yang-unknown-bit-types";
  prefix yang-ubt;

  // meta

  organization
    "IETF NETMOD (NETCONF Data Modeling Language) Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/netmod/>
     WG List:  <mailto:[email protected]>

     Editor:   Jeffrey Haas
               <mailto:[email protected]>";

  description
    "This module contains data definitions for modeling operational
     state that would normally be represented using the YANG 'bits'
     type, but currently no known mapping for that bit position is
     registered.

     Copyright (c) 2023 IETF Trust and the persons identified as
     authors of the code. All rights reserved.

     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 Simplified 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 XXXX
     (https://www.rfc-editor.org/info/rfcXXXX); 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.";

  revision 2023-01-25 {
    description
      "Initial Version";
    reference
      "RFC XXXX: YANG module for unknown bit types.";
  }

  /*
   * Typedefs
   */

  typedef unknown-bits {
    type bits {
      bit bit-0 {
        position 0;
        description
          "Bit 0 is unknown.";
      }
      bit bit-1 {
        position 1;
        description
          "Bit 1 is unknown.";
      }
      bit bit-2 {
        position 2;
        description
          "Bit 2 is unknown.";
      }
      bit bit-3 {
        position 3;
        description
          "Bit 3 is unknown.";
      }
      bit bit-4 {
        position 4;
        description
          "Bit 4 is unknown.";
      }
      bit bit-5 {
        position 5;
        description
          "Bit 5 is unknown.";
      }
      bit bit-6 {
        position 6;
        description
          "Bit 6 is unknown.";
      }
      bit bit-7 {
        position 7;
        description
          "Bit 7 is unknown.";
      }
      bit bit-8 {
        position 8;
        description
          "Bit 8 is unknown.";
      }
      bit bit-9 {
        position 9;
        description
          "Bit 9 is unknown.";
      }
      bit bit-10 {
        position 10;
        description
          "Bit 10 is unknown.";
      }
      bit bit-11 {
        position 11;
        description
          "Bit 11 is unknown.";
      }
      bit bit-12 {
        position 12;
        description
          "Bit 12 is unknown.";
      }
      bit bit-13 {
        position 13;
        description
          "Bit 13 is unknown.";
      }
      bit bit-14 {
        position 14;
        description
          "Bit 14 is unknown.";
      }
      bit bit-15 {
        position 15;
        description
          "Bit 15 is unknown.";
      }
      bit bit-16 {
        position 16;
        description
          "Bit 16 is unknown.";
      }
      bit bit-17 {
        position 17;
        description
          "Bit 17 is unknown.";
      }
      bit bit-18 {
        position 18;
        description
          "Bit 18 is unknown.";
      }
      bit bit-19 {
        position 19;
        description
          "Bit 19 is unknown.";
      }
      bit bit-20 {
        position 20;
        description
          "Bit 20 is unknown.";
      }
      bit bit-21 {
        position 21;
        description
          "Bit 21 is unknown.";
      }
      bit bit-22 {
        position 22;
        description
          "Bit 22 is unknown.";
      }
      bit bit-23 {
        position 23;
        description
          "Bit 23 is unknown.";
      }
      bit bit-24 {
        position 24;
        description
          "Bit 24 is unknown.";
      }
      bit bit-25 {
        position 25;
        description
          "Bit 25 is unknown.";
      }
      bit bit-26 {
        position 26;
        description
          "Bit 26 is unknown.";
      }
      bit bit-27 {
        position 27;
        description
          "Bit 27 is unknown.";
      }
      bit bit-28 {
        position 28;
        description
          "Bit 28 is unknown.";
      }
      bit bit-29 {
        position 29;
        description
          "Bit 29 is unknown.";
      }
      bit bit-30 {
        position 30;
        description
          "Bit 30 is unknown.";
      }
      bit bit-31 {
        position 31;
        description
          "Bit 31 is unknown.";
      }
      bit bit-32 {
        position 32;
        description
          "Bit 32 is unknown.";
      }
      bit bit-33 {
        position 33;
        description
          "Bit 33 is unknown.";
      }
      bit bit-34 {
        position 34;
        description
          "Bit 34 is unknown.";
      }
      bit bit-35 {
        position 35;
        description
          "Bit 35 is unknown.";
      }
      bit bit-36 {
        position 36;
        description
          "Bit 36 is unknown.";
      }
      bit bit-37 {
        position 37;
        description
          "Bit 37 is unknown.";
      }
      bit bit-38 {
        position 38;
        description
          "Bit 38 is unknown.";
      }
      bit bit-39 {
        position 39;
        description
          "Bit 39 is unknown.";
      }
      bit bit-40 {
        position 40;
        description
          "Bit 40 is unknown.";
      }
      bit bit-41 {
        position 41;
        description
          "Bit 41 is unknown.";
      }
      bit bit-42 {
        position 42;
        description
          "Bit 42 is unknown.";
      }
      bit bit-43 {
        position 43;
        description
          "Bit 43 is unknown.";
      }
      bit bit-44 {
        position 44;
        description
          "Bit 44 is unknown.";
      }
      bit bit-45 {
        position 45;
        description
          "Bit 45 is unknown.";
      }
      bit bit-46 {
        position 46;
        description
          "Bit 46 is unknown.";
      }
      bit bit-47 {
        position 47;
        description
          "Bit 47 is unknown.";
      }
      bit bit-48 {
        position 48;
        description
          "Bit 48 is unknown.";
      }
      bit bit-49 {
        position 49;
        description
          "Bit 49 is unknown.";
      }
      bit bit-50 {
        position 50;
        description
          "Bit 50 is unknown.";
      }
      bit bit-51 {
        position 51;
        description
          "Bit 51 is unknown.";
      }
      bit bit-52 {
        position 52;
        description
          "Bit 52 is unknown.";
      }
      bit bit-53 {
        position 53;
        description
          "Bit 53 is unknown.";
      }
      bit bit-54 {
        position 54;
        description
          "Bit 54 is unknown.";
      }
      bit bit-55 {
        position 55;
        description
          "Bit 55 is unknown.";
      }
      bit bit-56 {
        position 56;
        description
          "Bit 56 is unknown.";
      }
      bit bit-57 {
        position 57;
        description
          "Bit 57 is unknown.";
      }
      bit bit-58 {
        position 58;
        description
          "Bit 58 is unknown.";
      }
      bit bit-59 {
        position 59;
        description
          "Bit 59 is unknown.";
      }
      bit bit-60 {
        position 60;
        description
          "Bit 60 is unknown.";
      }
      bit bit-61 {
        position 61;
        description
          "Bit 61 is unknown.";
      }
      bit bit-62 {
        position 62;
        description
          "Bit 62 is unknown.";
      }
      bit bit-63 {
        position 63;
        description
          "Bit 63 is unknown.";
      }
    }
    description
      "Typedef describing 64 bits worth of unknown bits.  This can be
       used to model operational state that would normally be modeled
       using the YANG 'bits' type, but no registered bit has been
       created.";
  }
}
Figure 10

5. IANA Considerations

This document registers one URI and one YANG module.

5.1. URI Registration

Following the format in the IETF XML registry [RFC3688] [RFC3688], the following registration is requested to be made:

URI: urn:ietf:params:xml:ns:yang:ietf-yang-unknown-bit-types
Figure 11

Registrant Contact: The IESG. XML: N/A, the requested URI is an XML namespace.

5.2. YANG Module Name Registration

This document registers one YANG module in the YANG Module Names registry YANG [RFC6020].

name: ietf-yang-unknown-bit-types
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-unknown-bit-types
prefix: yang-ubt
reference: RFC XXXX
Figure 12

6. Security Considerations

Lack of operational visibility for protocol state can make troubleshooting protocol issues more difficult. The mechanism defined in this document may help reduce the scope of such issues and potentially remove the security considerations such lack of operational visibility may cause.

7. References

7.1. Normative References

[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.

7.2. Informative References

[RFC3688]
Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, , <https://www.rfc-editor.org/info/rfc3688>.
[RFC4724]
Sangli, S., Chen, E., Fernando, R., Scudder, J., and Y. Rekhter, "Graceful Restart Mechanism for BGP", RFC 4724, DOI 10.17487/RFC4724, , <https://www.rfc-editor.org/info/rfc4724>.
[RFC6020]
Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, , <https://www.rfc-editor.org/info/rfc6020>.
[RFC8538]
Patel, K., Fernando, R., Scudder, J., and J. Haas, "Notification Message Support for BGP Graceful Restart", RFC 8538, DOI 10.17487/RFC8538, , <https://www.rfc-editor.org/info/rfc8538>.
[I-D.ietf-idr-bgp-model]
Jethanandani, M., Patel, K., Hares, S., and J. Haas, "YANG Model for Border Gateway Protocol (BGP-4)", Work in Progress, Internet-Draft, draft-ietf-idr-bgp-model-16, , <https://datatracker.ietf.org/doc/html/draft-ietf-idr-bgp-model-16>.

Acknowledgements

Martin Bjorklund provided a review on an early version of this document.

Thanks to Jurgen Schonwalder and the IETF netmod Working Group for their feedback.

Author's Address

Jeffrey Haas
Juniper Networks
1133 Innovation Way
Sunnyvale, CA 94089
United States of America