Internet-Draft YANG-CMIS-Access-Control June 2025
Homma, et al. Expires 22 December 2025 [Page]
Workgroup:
CCAMP Working Group
Internet-Draft:
draft-hi-ccamp-cmis-control-yang-00
Published:
Intended Status:
Standards Track
Expires:
Authors:
S. Homma, Ed.
NTT
H. Irino, Ed.
NTT
T. Mano
NTT
K. Anazawa
NTT

A YANG Data Model for CMIS Access and Control

Abstract

This document provides a YANG data model to access to and control CMIS for controlling Digital Coherent Optics device equipped in a router or a switch from outside. CMIS has custom pages which enables to be defined by the module vendor for its own usage, and allows to extend the uses of the optics devices.

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 22 December 2025.

▲

Table of Contents

1. Introduction

Digital Coherent Optics (DCO) modules enable routers or switches to directly connect to transport network, such as Optical Transport Network (e.g., DWDM or OTN) or Wavelength Division Multiplexing (WDM) network. DCO modules, such as CFP2-DCO and QSFP-DD DCO, implement optical connector (i.e., Tx and Rx) and Digital Signal Processor (DSP), and provide higher data rates (100 Gbps, 400 Gbps, and beyond) and flexible data transport.

DCO transceivers, equipped by a platform device (e.g., a switch or a router), is generally controlled by network OS running on the device with Content Management Interoperability Specifications (CMIS) which is an open standard protocol designed to facilitate interoperability between management systems. The specification is defined in [OIF-CMIS]. CMIS also allows vendor-specific extensions of its transceiver features by using custom pages. For example, CMIS custom pages can be used for debugs of the transceiver. This document defines a YANG data model for accessing to and controlling CMIS for controlling DCO transceivers from outside of the platform device.

1.1. Terminology and Notations

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" this document are to be interpreted as described in BCP14, [RFC2119], [RFC8340] when, and only when, they appear in all capitals, as shown here.

The terms and their definitions used in this specification are described below:

  • CMIS (Common Management Interface Specifications): A generic management communication interface together with a generic management interaction protocol between host and managed modules. The specification is defined in [OIF-CMIS];

  • NACM (Network Configuration Access Control Model): A standard access control model to restrict NETCONF or RESTCONF protocol access for particular users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. The specification is defined in [RFC8341].

  • NETCONF (Network Configuration Protocol): Mechanisms to install, manipulate, and delete the configuration of network devices. The definitions and specification is described in [RFC6241];

  • RESTCONF: An HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in NETCONF. The specification is defined in [RFC8040].

The following terms of NETCONF defined in [RFC6241] are also used in this specification:

  • (NETCONF) client

  • configuration data

  • datastore

  • message

  • remote procedure call (RPC)

  • (NETCONF) server

  • state data

  • (NETCONF) user

This document makes use of the terms defined in [RFC7950].

1.2. Acronyms

The following acronyms are used in this document:

CE
Customer Edge
CDB
Command Data Block
DCO
Digital Coherent Optics
DSP
Digital Signal Processor
DWDM
Dense Wavelength Division Multiplexing
GSNR
Generalized Signal-to-Noise Ratio
i2c
Inter-Integrated Circuit
NOS
Network Operating System
NMS
Network Management System
OTN
Optical Transport Network
QoT
Quality of Transmission
TPA
Third Party Application
WDM
Wavelength Division Multiplexing

1.3. Tree Diagram

The tree diagrams used in this document follow the notation defined in [RFC8340].

1.4. Prefixes in Data Node Names

In this document, names of data nodes and other data model objects are prefixed using the standard prefix associated with the corresponding YANG imported modules.

Table 1: Prefixes and corresponding YANG module
Prefix YANG module Reference
if ietf-interfaces [RFC7223]
cmis-ctrl ietf-cmis-control RFC XXXX

Note: The RFC Editor will replace XXXX with the number assigned to the RFC once this draft becomes an RFC.

2. Usecases and Implementation Patterns

This section describes usecases of this YANG data model for accessing to and control CMIS and implementation patterns for using such YANG.

2.1. Usecases

2.1.1. Centralized Control of Pluggable Modules

This YANG data model disaggregates management features for pluggable modules which a platform device equips with from NOS, and enables centralized control of such modules. For example, in case that a customer's router (i.e., CE) is connected to DWDM/OTN provided by a service provider, this enables pluggable optics modules installed to the customer's router to be controlled by a controller of the service provider as shown in Figure 1. The service provider can configure DCO transceivers installed in customer devices directly depending on its own policy. Then, some access control with NACM defined in [RFC8341] should be applied for preventing illegal configuration of the other than target modules or leak of information of the customer's devices.


                         +-------------+
                   . . . | Contrroller |. . .
                   .     +-------------+    .
                   .           .            .
   ,--------.      .           .            .      ,--------.
  (          )     .       ,--------.       .     (          )
 ( Customer +----+ .      (          )      . +----+ Customer )
(   Network | CE [DCO]---(  DWDM/OTN  )---[DCO] CE |  Network  )
 (          +----+        (          )        +----+          )
  `----------'             `--------'             `----------'

`-------v-------' `------------v------------' `--------v------'
 Customer Domain    Service Provider Domain    Customer Domain

                                      Legend
                                      . . . : C-plane Interface
Figure 1: Centralized Control of Pluggable Modules

On the other hand, in case that NOS of the platform device manages pluggable modules, CMIS control from remote controller might cause inconsistency problem of pluggable modules. More details of this problem is considered in Section 6.

2.1.2. Obtaining Non-standardized Information with Custom Pages

By using this YANG data model, operators can obtain detailed DSP information contained in CMIS custom pages even if the modeling of the data is not standardized. Example uses of such detailed DSP information including fiber sensing (Ref. [ECOC48923.2020.9333176]), physical layer monitoring (Ref. [JLT.2021.3139167]), and accurate estimation (e.g., GSNR) (Ref. [JOCN.505729]).

2.2. Implementation Patterns

This document introduce two patterns to implement a client using an interface in which this YANG data model is available:

Pattern1:
Controller/NMS on Remote Host
In this pattern, a controller or an NMS implements a client using this YANG data model, and control pluggable modules installed to a platform device. The overview is shown in Figure 2.
Pattern2:
Application Running on the Platform Device
In this pattern, a 3rd party's application running on a platform device implements a client using this YANG data model, and control pluggable modules installed to the device. That application can behave as a server using this YANG data model, or provide more generic interface, such as REST API to remote systems. The overview is shown in Figure 3. 

+-----------------------+
|    Controller/NMS     |
+-----------------------+
            A
            | This YANG over NETCONF,
            | RESTCONF or RPC.
            |
            V
+-----------------------+
|   Platform Device     |
|   ,---------------.   |
|  |       NOS       |  |
|   `---------------'   |
|           A           |
|           | CMIS via  |
|           V i2c bus   |
|       +-------+       |
+-------|  DCO  |-------+
        +-------+
Figure 2: Implementation Pattern1 Overview 

+-----------------------+
|    Controller/NMS     |
+-----------------------+
            A
            | This YANG over NETCONF/
            | RESTCONF/RPC,or REST API.
            +------+
+------------------|----+
| Platform Device  |    |
|                  V    |
| This YANG over ,---.  |
| NETCONF etc.  | TPA | |
|       +-----> | APL | |
|       |        `---'  |
|   ,---V-----------.   |
|  |       NOS       |  |
|   `---------------'   |
|           A           |
|           | CMIS via  |
|           V i2c bus   |
|       +-------+       |
+-------|  DCO  |-------+
        +-------+
Figure 3: Implementation Pattern2 Overview

3. CMIS Access and Control Model and Contents

The ietf-cmis-control is an augment to the ietf-interface. It allows the user to set the operating mode of CMIS for control pluggable devices as well as other operational parameters. cmis-control. The structure is shown below:

module: ietf-cmis-control

  augment /if:interfaces/if:interface:
    +--rw cmis-control
       +--ro cmis-enabled?   boolean
       +--ro cmis-version?   string
       +--rw cmis-page* [page-num]
          +--rw page-num            uint8
          +--rw bank                uint8
          +--ro page-access-type?   access-type
          +--rw description?        string
          +--rw value* [offset]
             +--rw offset               uint8
             +--rw size                 uint8
             +--ro value-access-type?   access-type
             +--rw value-data           binary
             +--rw description?         string

The "ietf-cmis-control" module contains the following YANG reusable YANG data types, identities and groupings:

cmis-control:

A base YANG identity for data nodes to access and control CMIS supported by the pluggable device equipped in the interface.

cmis-version:

A base YANG identity for the version of CMIS supported by the device.

cmis-pages:

A base YANG identity for the list of pages to be accessed or controlled.

cmis-page:

A base YANG identity for the page to be accessed or controlled.

cmis-page:page-num:

A base YANG identity for the number of the target CMIS page. The value is selected from 0 to 255.

cmis-page:bank:

A base YANG identity for the bank corresponding to the target CMIS page.

cmis-page:page-access-type:

A base YANG identity for access type of the target CMIS page. An access type is selected from among rw (A readable and writable element), rww (A readable and writable element that can be modified by the module), ro (A read-only element), wo(A write-only element), wo/sc (A write-only element with self-clearing side effect), and ro/cor (A write-only element with clean-on-read side effect).

cmis-page:description:

A base YANG identity for the description about the content of the target CMIS page.

cmis-page:value:

A base YANG identity for the subject area to be controlled.

value:offset

A base YANG identity for the location of the data within about the target CMIS page. The value is selected from 0 to 255.

value:size

A base YANG identity for the size of the value. The value is selected from 1 to 128.

value:value-access-type:

A base YANG identity for access type of the value. An access type is selected from among rw, rww, ro, wo, wo/sc, and ro/cor.

value:value-data

A base YANG identity for the data contained into the value. The data format is basically binary, but any other format (e.g., ASCII, JIS) can be also used. The length of the value must be the same with the indicated size. The value is writable only when the access-type is neither ro or ro/cor. In case that the value is across multiple subject areas which have different access-types, all access-type conditions must be satisfied. For example, if the value across subject-areas whose access-types are ro and rw, the access-type of the value is ro. When all conditions cannot be satisfied (e.g., ro and wo co-exists), an error should be responded.

value:description

A base YANG identity for the description of the value.

4. YANG Module for CMIS Acccess and Control

The ietf-cmis-control is defined as an extension to ietf-interfaces.

<CODE BEGINS> file "ietf-cmis-control.yang"

module ietf-cmis-control {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-cmis-control";
  prefix cmis-ctrl;

  import ietf-interfaces {
    prefix if;
  }

  organization
    "IETF CCAMP Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/ccamp/>
    WG List:  <mailto:ccamp@ietf.org>

    Editor:   Shunsuke Homma
      <mailto:shunsuke.homma.ietf@gmail.com>

    Editor:   Hitoshi Irino
      <mailto:hitoshi.irino@ntt.com>";

  description
    "This YANG module defines a data model for the management
    of CMIS (Common Management Interface Specification) pages
    as specified by OIF. It enables configuration and retrieval
    of CMIS page data, including access types and value fields,
    to support the management of pluggable optical modules via
    NETCONF or RESTCONF.

    Copyright (c) 2025 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 Revised
    BSD License set forth in Section 4.c of the IETF Trust's
    Legal Provisions Relating to IETF Documents
    (http://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.";

// RFC Ed.: replace XXXX with actual RFC number and remove this note

  revision "2025-04-21" {
    description
      "Initial revision.";
    reference
      "I-D.hi-ccamp-cmis-control-yang-00";
  }

  /*
   * CMIS control data nodes
   */

  typedef access-type {
      type enumeration {
        enum rw {
          description "A readable and writable element.";
        }
        enum rww {
          description "A readable and writable element that can be
          modified by the module.";
        }
        enum ro {
          description "A read-only element.";
        }
        enum wo {
          description "A write-only element.";
        }
        enum wo/sc {
          description "A write-only element with self-clearing side
          effect.";
        }
        enum ro/cor {
          description "A write-only element with celan-on-read side
          effect.";
        }
      }
      description "Defines access types for CMIS elements.";
  }

  grouping cmis-page {
    description
      "Parameters stored in the CMIS page";

    leaf page-num{
      type uint8 {
        range "0 .. 255";
      }
      mandatory true;
      description
        "The number of the CMIS page.";
    }

    leaf bank {
      type uint8;
      mandatory true;
      description
        "The banks corresponding to the CMIS page.";
    }

    leaf page-access-type {
      type access-type;
      config false;
      description "Access type of the CMIS page.";
    }

    leaf description {
      type string;
      description
        "The description of the CMIS page.";
    }

    list value {
      key "offset";
      description
      "The value contained in the CMIS page.";

      leaf offset {
        type uint8;
        mandatory true;
        description
          "The memory address of the value.";
      }

      leaf size {
        type uint8 {
          range "1 .. 128";
        }
        mandatory true;
        description
          "The memory size of the value.";
      }

      leaf value-access-type {
        type access-type;
        config false;
        description "Access type of the target value.";
      }

      leaf value-data {
        type binary;
        mandatory true;
        description
          "The data contained in the value. It is writable only
          when the access-type is not Read-Only or Read-Only with
          clean-on-read side effect.";
      }

      leaf description {
        type string;
        description
          "The description of the value.";
      }
    }
  }


  grouping cmis-pages {
    description
      "The list of the accessible CMIS pages supported by the
      pluggable device accommodated into the interface.";

    list cmis-page {
      key "page-num";
      uses cmis-page;
      }
  }

  grouping cmis-control {
    description
      "Parameters for primitive CMIS control of the pluggable device
      equipped in the interface.";

    leaf cmis-enabled {
      type boolean;
      default "false";
      config false;
      description
        "The availability of the CMIS for control the pluggable
        device equipped in the interface. If the device does not
        support CMIS, this value is false.";
    }

    leaf cmis-version {
      type string;
      config false;
      description
        "The version of the CMIS by the pluggable device.";
    }

    uses cmis-pages;

  }

  /*
   * Augment Interface
   */

  augment "/if:interfaces/if:interface" {
    container cmis-control {
      uses cmis-control;
    }
  }
}

<CODE ENDS>

5. Primitive Mode

This section provides a more primitive YANG data model for CMIS access and control. This is called as "Primitive Mode" and it doesn't manage supplemental information, such as access-types or description, of the fields in a CMIS page, and treat accessed memories as flat data structure.

This mode enables implementation of client side be simple, but on the other hand, server side is needed strict management of data of CMIS pages. For example, when a server is changing any value, the server need to comprehend the page number, the offset, and the data size in which the data is contained.

5.1. YANG Module Identities and Structure

The name of data node and prefix are described in Table 2. This module is also an augment to the ietf-interface.

Table 2: Data Node Name and Prefix of Primitive Mode
Prefix YANG module Reference
if ietf-interfaces [RFC7223]
cmis-ctrl-pm ietf-cmis-control-primitive RFC YYYY

The tree diagram of ietf-cmis-control-primitive is shown below:

module: ietf-cmis-control-primitive

  augment /if:interfaces/if:interface:
    +--rw cmis-control-primitive
       +--ro cmis-enabled?          boolean
       +--ro cmis-version?          string
       +--rw primitive-cmis-page* [page-num]
          +--rw page-num    uint8
          +--rw bank        uint8
          +--rw offset      uint8
          +--rw size        uint8
          +--rw value       binary

5.2. Primitive Mode YANG Module for CMIS Access and Control

The ietf-cmis-control-primitive is also defined as an extension to ietf-interfaces.

<CODE BEGINS> file "ietf-cmis-control-primitive.yang"

module ietf-cmis-control-primitive {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-cmis-control-primitive";
  prefix cmis-ctrl-pm;

  import ietf-interfaces {
    prefix if;
  }

  organization
    "IETF CCAMP Working Group";

  contact
    "WG Web:   <http://tools.ietf.org/wg/ccamp/>
    WG List:  <mailto:ccamp@ietf.org>

    Editor:   Shunsuke Homma
      <mailto:shunsuke.homma.ietf@gmail.com>

    Editor:   Hitoshi Irino
      <mailto:hitoshi.irino@ntt.com>";

  description
    "This YANG module defines a primitive data model for the
    management of CMIS (Common Management Interface Specification)
    pages as specified by OIF. It enables configuration and
    retrieval of CMIS page data, including access types and value
    fields, to support the management of pluggable optical modules
    via NETCONF or RESTCONF.

    Copyright (c) 2025 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 Revised
    BSD License set forth in Section 4.c of the IETF Trust's
    Legal Provisions Relating to IETF Documents
    (http://trustee.ietf.org/license-info).

    This version of this YANG module is part of RFC XXXX
    (https://www.rfc-editor.org/info/rfc YYYY); see the RFC itself
    for full legal notices.";

// RFC Ed.: replace XXXX with actual RFC number and remove this note

  revision "2025-04-21" {
    description
      "Initial revision.";
    reference
      "I-D.hi-ccamp-cmis-control-yang-00";
  }

  /*
   * Primitive Mode of CMIS control data nodes
   */

  grouping primitive-cmis-page {
    description
      "Parameters stored in the CMIS page as flat data structure";

    leaf page-num{
      type uint8 {
        range "0 .. 255";
      }
      mandatory true;
      description
        "The number of the CMIS page.";
    }

    leaf bank {
      type uint8;
      mandatory true;
      description
        "The banks corresponding to the CMIS page.";
    }


    leaf offset {
      type uint8;
      mandatory true;
      description
        "The memory address of the value.";
    }

    leaf size {
      type uint8 {
        range "1 .. 128";
      }
      mandatory true;
      description
        "The memory size of the value.";
    }

    leaf value {
      type binary;
      mandatory true;
      description
        "The actual data to write to the CMIS memory.";
    }
  }

  grouping cmis-control-primitive {
    description
      "Parameters for primitive CMIS control of the pluggable
      device equipped in the interface.";

    leaf cmis-enabled {
      type boolean;
      default "false";
      config false;
      description
        "The availability of the CMIS for control the pluggable
        device equipped in the interface. If the device does not
        support CMIS, this value is false.";
    }

    leaf cmis-version {
      type string;
      config false;
      description
        "The version of the CMIS by the pluggable device.";
    }

    list primitive-cmis-page {
      key "page-num";
      config true;
      uses primitive-cmis-page;
    }
  }

  /*
   * Augment Interface
   */

  augment "/if:interfaces/if:interface" {
    container cmis-control-primitive {
      uses cmis-control-primitive;
    }
  }
}

<CODE ENDS>

6. Security Consideration

This YANG allows remote systems to control the equipped pluggable devices directly. It might cause conflict of management of the pluggable devices among the platform node and remote systems. For avoiding this problem, only the minimum necessary CMIS pages (e.g., custom pages) should be exposed to external by using access control features such as [RFC8341].

Regarding to use of the primitive mode, the control rights of the accessible pages are delegated to a controller. Therefore, it is recommended that the mode is used in case that the controller can be trusted, for example, the controlled device and controller are managed by the same operator. Otherwise, specific pages which may affect on data plane signaling should not exposed by using access control features such as [RFC8341]

7. IANA Considerations

This document requests IANA to register the following YANG modules in the "YANG Module Names" registry [RFC6020] within the "YANG Parameters" registry group.

   Name:  ietf-cmis-control
   Maintained by IANA?  N
   Namespace:  urn:ietf:params:xml:ns:yang:ietf-cmis-ctrl
   Prefix:  cmis-ctrl
   Reference:  RFC XXXX

   Name:  ietf-cmis-control-primitive
   Maintained by IANA?  N
   Namespace:  urn:ietf:params:xml:ns:yang:ietf-cmis-ctrl-pm
   Prefix:  cmis-ctrl-pm
   Reference:  RFC YYYY

8. References

8.1. Normative References

[OIF-CMIS]
OIF, "Common Management Interface Specification (CMIS) Revision 5.2", .
[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>.
[RFC7223]
Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, , <https://www.rfc-editor.org/info/rfc7223>.
[RFC7950]
Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, , <https://www.rfc-editor.org/info/rfc7950>.
[RFC8340]
Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, , <https://www.rfc-editor.org/info/rfc8340>.

8.2. Informative References

[ECOC48923.2020.9333176]
Cantono, M., Kamalov, V., Salsi, M., Newland, M., and Z. Zhan, "Sub-Hertz Spectral Analysis of Polarization of Light in a Transcontinental Submarine Cable", European Conference on Optical Communications ECOC 2020, DOI 10.1109/ECOC48923.2020.9333176, , <https://doi.org/10.1109/ECOC48923.2020.9333176>.
[JLT.2021.3139167]
Sasai, T., Nakamura, M., Yamazaki, E., Yamamoto, S., Nishizawa, H., and Y. Kisaka, "Digital Longitudinal Monitoring of Optical Fiber Communication Link", Journal of Lightwave Technology volume:40, DOI 10.1109/JLT.2021.313917, , <https://doi.org/10.1109/JLT.2021.313917>.
[JOCN.505729]
Nishizawa, H., Mano, T., Ferreira de Lima, T., Huang, Y., Wang, Z., Ishida, W., Kawashima, M., Ip, E., D'Amico, A., Okamoto, S., Inoue, T., Anazawa, K., Curri, V., Zussman, G., Kilper, D., Chen, T., Wang, T., Asahi, K., and K. Takasugi, "Fast WDM provisioning with minimal probing: the first field experiments for DC exchanges", JOCN 505729, DOI 10.1364/JOCN.505729, , <https://doi.org/10.1364/JOCN.505729>.
[RFC6241]
Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, , <https://www.rfc-editor.org/info/rfc6241>.
[RFC8040]
Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, , <https://www.rfc-editor.org/info/rfc8040>.
[RFC8341]
Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, , <https://www.rfc-editor.org/info/rfc8341>.

Authors' Addresses

Shunsuke Homma (editor)
NTT
Hitoshi Irino (editor)
NTT
Toru Mano
NTT
Kazuya Anazawa
NTT