YANG Extension and Metadata Annotation for Immutable Flag

1.2. Applicability

The "immutable" concept defined in this document only documents existing write access restrictions to writable datastores. A particular data node or instance has the same immutability in all writable datastores. The immutable annotation information is also visible even in read-only datastores like <system> (if exists), <intended> and <operational> when a "with-immutable" parameter is carried (see Section 6.2), however this only serves as descriptive information about the instance node itself, but has no effect on the handling of the read-only datastore. The immutability of data nodes is protocol and user independent.¶

9.1. The "IETF XML" Registry

This document registers one XML namespace URN in the 'IETF XML registry', following the format defined in [RFC3688].¶

URI: urn:ietf:params:xml:ns:yang:ietf-immutable
Registrant Contact: The IESG.
XML: N/A, the requested URIs are XML namespaces.

9.2. The "YANG Module Names" Registry

This document registers one module name in the 'YANG Module Names' registry, defined in [RFC6020].¶

name: ietf-immutable
prefix: im
namespace: urn:ietf:params:xml:ns:yang:ietf-immutable
RFC: XXXX
// RFC Ed.: replace XXXX and remove this comment

A.1. UC1 - Modeling of server capabilities

System capabilities might be represented as system-defined data nodes in the model. Configurable data nodes might need constraints specified as "when", "must" or "path" statements to ensure that configuration is set according to the system's capabilities. E.g.,¶

• A timer can support the values 1,5,8 seconds. This is defined in the leaf-list 'supported-timer-values'.¶
• When the configurable 'interface-timer' leaf is set, it should be ensured that one of the supported values is used. The natural solution would be to make the 'interface-timer' a leaf-ref pointing at the 'supported-timer-values'.¶

However, this is not possible as 'supported-timer-values' must be read-only thus config=false while 'interface-timer' must be writable thus config=true. According to the rules of YANG it is not allowed to put a constraint between config true and false data nodes.¶

The solution is that the supported-timer-values data node in the YANG Model shall be defined as "config true" and shall also be marked with the "immutable" extension making it unchangable. After this the 'interface-timer' shall be defined as a leaf-ref pointing at the 'supported-timer-values'.¶

A.2. UC2 - HW based auto-configuration - Interface Example

This section shows how to use immutable YANG extension to mark some data node as immutable.¶

When an interface is physically present, the system will create an interface entry automatically with valid name and type values in <system> (if exists, see [I-D.ietf-netmod-system-config]). The system-generated data is dependent on and must represent the HW present, and as a consequence must not be changed by the client. The data is modelled as "config true" and should be marked as immutable.¶

Seemingly an alternative would be to model the list and these leaves as "config false", but that does not work because:¶

• The list cannot be marked as "config false", because it needs to contain configurable child nodes, e.g., ip-address or enabled;¶
• The key leaf (name) cannot be marked as "config false" as the list itself is config true;¶
• The type cannot be marked "config false", because we MAY need to reference the type to make different configuration nodes conditionally available.¶

The immutability of the data is the same for all interface instances, thus following fragment of a fictional interface module including an "immutable" YANG extension can be used:¶

     container interfaces {
       list interface {
         key "name";
         leaf name {
           type string;
         }
         leaf type {
           im:immutable;
           type identityref {
             base ianaift:iana-interface-type;
           }
           mandatory true;
         }
         leaf mtu {
           type uint16;
         }
         leaf-list ip-address {
           type inet:ip-address;
         }
       }
     }

Note that the "name" leaf is defined as a list key which can never been modified for a particular list entry, there is no need to mark "name" as immutable.¶

<rpc message-id="101"
     xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
     xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <running/>
    </target>
    <config>
      <interface xc:operation="merge"
            xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">
        <name>eth0</name>
        <type>ianaift:tunnel</type>
      </interface>
    </config>
  </edit-config>
</rpc>

<rpc-reply message-id="101"
           xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
           xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <rpc-error>
    <error-type>application</error-type>
    <error-tag>invalid-value</error-tag>
    <error-severity>error</error-severity>
    <error-path xmlns:t="http://example.com/schema/1.2/config">
      /interfaces/interface[name="eth0"]/type
    </error-path>
    <error-message xml:lang="en">
      Invalid type for interface eth0
    </error-message>
  </rpc-error>
</rpc-reply>

A.3. UC3 - Predefined Access control Rules

Setting up detailed rules for access control is a complex task. (see [RFC8341]) A vendor may provide an initial, predefined set of groups and related access control rules so that the customer can use access control out-of-the-box. The customer may continue using these predefined rules or may add his own groups and rules. The predefined groups shall not be removed or altered guaranteeing that access control remains usable and basic functions e.g., a system-security-administrator are always available.¶

The system needs to protect the predefined groups and rules, however, the list "groups" or the list "rule-list" cannot be marked as config=false or with the "immutable" extension in the YANG model because that would prevent the customer adding new entries. Still it would be good to notify the client in a machine readable way that the predefined entries cannot be modified. When the client retrieves access control data the immutable="true" metadata annotation should be used to indicate to the client that the predefined groups and rules cannot be modified.¶

A.4. UC4 - Declaring System defined configuration unchangeable

As stated in [I-D.ietf-netmod-system-config] the device itself might supply some configuration. As defined in that document in section "5.4. Modifying (overriding) System Configuration" the server may allow some parts of system configuration to be modified while other parts of the system configuration are non-modifiable. The immutable extension or metadata annotation can be used to define which parts are non-modifiable and to inform the client about this fact.¶

A.5. UC5 - Immutable BGP peer type

Another example is the type attribute of BGP neighbors. The peer type of the BGP neighbor is closely related to the network topology: external BGP (EBGP) peer type relationships are established between BGP routers running in different ASs; while internal BGP (IBGP) peer type relationships are established between BGP routers running in the same AS. Thus BGP peer type cannot be changed to the value which does not match the actual one. Since there are EBGP/IBGP-specific configurations which need to reference the "peer-type" node (e.g., in "when" statement) and be conditionally available, it can only be modelled as "config true" but immutable.¶

Following is the fragment of a simplified BGP module with the /bgp/neighbor/peer-type defined as immutable:¶

container bgp {
  leaf as {
    type inet:as-number;
    mandatory true;
    description
      "Local autonomous system number of the router.";
  }
  list neighbor {
    key "remote-address";
    leaf remote-address {
      type inet:ip-address;
      description
        "The remote IP address of this entry's BGP peer.";
    }
    leaf peer-type {
      im:immutable;
      type enumeration {
        enum ebgp {
         description
           "External (EBGP) peer.";
        }
        enum ibgp {
          description
            "Internal (IBGP) peer.";
        }
      }
      mandatory true;
      description
        "Specify the type of peering session associated with this
         neighbor. The value can be IBGP or EBGP.";
    }
    leaf ebgp-max-hop {
      when "../peer-type='ebgp'";
      type uint32 {
        range "1..255";
      }
      description
        "The maximum number of hops when establishing an EBGP peer
         relationship with a peer on an indirectly-connected network.
         By default, an EBGP connection can be set up only on a
         directly-connected physical link.";
    }
  }
}

A.6. UC6 - Modeling existing data handling behavior in other standard organizations

A number of standard organizations and industry groups (ITU-T, 3GPP, ORAN) already use concepts similar to immutability. These modeling concepts sometimes go back to more than 10 years and cannot be and will not be changed irrespective of the YANG RFCs. Some of these organizations are introducing YANG modelling. Without a formal YANG statement to define data nodes immutable the property is only defined in plain English text in the description statement. The immutable flag can be used to define these existing model properties in a machine-readable way.¶