]> Juniper Networks

1133 Innovation Way Sunnyvale CA 94089 US jhaas@pfrc.org

Routing netmod 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.

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 when, and only when, they appear in all capitals, as shown here.

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 () 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.

Modeling Unknown Bits

Example of Issue: Modeling BGP's Graceful Restart Flags BGP's Graceful Restart Capability () contains a Restart Flags field that is four bits wide. Its definition is copied below:

BGP Graceful Restart Flags

The 'R' (Restart State) bit has been assigned in RFC 4724. One way to model this (taken from ) is:

BGP Graceful Restart Flags

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

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:

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 for 'R' and 'N' bits with original leaves and typedef restart ]]>

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:

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 for 'R' and 'N' bits with new leaves and typedefs restart bit-1 ]]>

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 for 'R' and 'N' bits with new leaves and updated typedef restart unknown ]]>

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:

BGP Graceful Restart Specific Unknown Bits with Typedef

IETF YANG Unknown Bit Types Module

WG List: Editor: Jeffrey Haas "; 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."; } } ]]>

IANA Considerations This document registers one URI and one YANG module.

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

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

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

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.

References Normative References Informative References

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.