| Internet-Draft | YANG Unknown Bits | April 2023 |
| Haas | Expires 12 October 2023 | [Page] |
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.¶
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.¶
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. 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.¶
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.¶
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.¶
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.| +-+-+-+-+¶
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.";
}
¶
[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| | +-+-+-+-+¶
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.";
}
}
}
¶
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>
¶
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.";
}
¶
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>
¶
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>
¶
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.";
}
¶
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:netmod@ietf.org>
Editor: Jeffrey Haas
<mailto:jhaas@juniper.net>";
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.";
}
}
¶
This document registers one URI and one YANG module.¶
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
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 [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
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.¶
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.¶