IVY Working Group C. Yu Internet-Draft Huawei Intended status: Standards Track A. Guo Expires: 25 April 2025 Futurewei I. Busi Huawei 22 October 2024 A YANG Data Model for Passive Network Inventory draft-ygb-ivy-passive-network-inventory-00 Abstract This document presents a YANG data model for passive device inventory information. The model enhances the base model outlined in [I-D.draft-ietf-ivy-network-inventory-yang] and is intended for use in the northbound interface of a domain controller as defined in [RFC8453]. 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 25 April 2025. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. Yu, et al. Expires 25 April 2025 [Page 1] Internet-Draft Passive Network Inventory YANG Model October 2024 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology and Notations . . . . . . . . . . . . . . . . . . 3 2.1. Requirements Notations . . . . . . . . . . . . . . . . . 3 2.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2.3. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 4 2.4. Prefixes in Data Node Names . . . . . . . . . . . . . . . 4 3. YANG Model Overview . . . . . . . . . . . . . . . . . . . . . 5 4. Model Tree Diagram . . . . . . . . . . . . . . . . . . . . . 5 5. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1. YANG Data Model for Passive Device Inventory . . . . . . 6 6. Manageability Considerations . . . . . . . . . . . . . . . . 17 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 9. Normative References . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 1. Introduction Passive devices typically include fiber, cable, optical splitters, and some passive sites. As a crucial part of communication networks, the inventory information for these devices is also essentialfor inventory management. [I-D.draft-ietf-ivy-network-inventory-yang] incorporates the component concept from [RFC8348] to detail the equipment and holder information of a NE. This encompasses chassis, slot/sub-slot, board/ sub-board, port, and transceiver. As these items are recognized by the NE through internal protocols, the passive devices that cannot be discovered by the NE are thus not included in the modeling and needs to be addressed. [I-D.draft-ietf-ivy-network-inventory-location] emphasizes the relative and geographic location, e.g. equipment room, geo-loation for NE. A passive device is deployed in a certain location visible by the operator, and thus can reference the location defined by [I-D.draft-ietf-ivy-network-inventory-location]. Yu, et al. Expires 25 April 2025 [Page 2] Internet-Draft Passive Network Inventory YANG Model October 2024 This document focuses on modeling passive device inventory. The methods for discovering these devices are implementation-specific and fall outside the scope of this document. 2. Terminology and Notations 2.1. Requirements Notations 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.2. Terminology The following terms are defined in [RFC7950] and are not redefined here: * client * server * augment * data model * data node The following terms are defined in [RFC6241] and are not redefined here: * configuration data * state data The following terms are defined and used in this document. * Passive device: refers to a physical device within a network that does not require external power to function, and simply manipulates signals through processes like transmission, reflection, splitting, filtering, or attenuation without actively amplifying or generating the signal. Examples include optical fibers, splitters, couplers, and optical filters, all of which are used to direct and manage light signals within a system without needing electricity. A passive device typically does not have management interfaces and is typically deployed in a location tracked by the network operator. Yu, et al. Expires 25 April 2025 [Page 3] Internet-Draft Passive Network Inventory YANG Model October 2024 * Active device: refers to a physical device that contains hardware and software and is managable through communication interfaces. Network elements defined by [I-D.draft-ietf-ivy-network-inventory-yang] are examples of active device. * Optical Cable: Refers to a wire that uses optical fiber as a medium to transmit optical signals. Optical cable is a concept of a collection, consisting of one or multiple optical cable segments connected by optical cable connectors. The equipment at both ends of the optical cable can be an optical distribution frame, an optical cross-connection box, or an optical splitter box. * Optical Cable Segment: refers to a section of optical cable where the number of fiber cores between two optical junctions remains unchanged. Optical cable segments can be spliced or fused through a joint box, connected through an optical distribution frame (ODF), or fiber jumpers. An optical fiber segment contains multiple fiber cores, or strands. 2.3. Tree Diagram Tree diagrams used in this document follow the notation defined in [RFC8340]. 2.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, as shown in Table 1. +========+========================+===========+ | Prefix | YANG Module | Reference | +========+========================+===========+ | ni | ietf-network-inventory | RFC XXXX | +--------+------------------------+-----------+ | nil | ietf-ni-location | RFC YYYY | +--------+------------------------+-----------+ Table 1: Prefixes and Corresponding YANG Modules RFC Editor Note: Please replace XXXX with the RFC number assigned to [I-D.draft-ietf-ivy-network-inventory-yang]. Please replace YYYY with the RFC number assigned to [I-D.draft-ietf-ivy-network-inventory-location]. Please remove this note. Yu, et al. Expires 25 April 2025 [Page 4] Internet-Draft Passive Network Inventory YANG Model October 2024 3. YANG Model Overview The YANG data model in this draft augments the model defined in [I-D.draft-ietf-ivy-network-inventory-yang] with the following information: - Passive devices: a list of passive devices with extended attributed reported by the domain controller. - Optical cables: a list of optical cables with each containing a list of cable segments. 4. Model Tree Diagram module: ietf-ni-passive-device augment /ni:network-inventory: +--rw optical-cable* [id] | +--rw id string | +--ro uuid? yang:uuid | +--rw name? string | +--rw description? string | +--rw alias? string | +--rw cable-type? identityref | +--rw fiber-core-num? uint32 | +--rw a-end | | +--rw device-type? identityref | | +--rw (connected-device-type)? | | +--:(passive) | | | +--rw device-id? string | | +--:(active) | | +--rw ne-ref? leafref | | +--rw component-ref? leafref | +--rw z-end | | +--rw device-type? identityref | | +--rw (connected-device-type)? | | +--:(passive) | | | +--rw device-id? string | | +--:(active) | | +--rw ne-ref? leafref | | +--rw component-ref? leafref | +--rw optical-cable-segment* [id] | +--rw id string | +--ro uuid? yang:uuid | +--rw name? string | +--rw description? string | +--rw alias? string | +--rw fiber-core-num? uint32 | +--rw fiber-type? identityref | +--rw length? uint32 | +--rw attenuation? decimal64 Yu, et al. Expires 25 April 2025 [Page 5] Internet-Draft Passive Network Inventory YANG Model October 2024 | +--rw serial-num? string | +--rw mfg-name? string | +--rw part-number? string | +--rw a-end | | +--rw device-type? identityref | | +--rw (connected-device-type)? | | +--:(passive) | | | +--rw device-id? string | | +--:(active) | | +--rw ne-ref? leafref | | +--rw component-ref? leafref | +--rw z-end | +--rw device-type? identityref | +--rw (connected-device-type)? | +--:(passive) | | +--rw device-id? string | +--:(active) | +--rw ne-ref? leafref | +--rw component-ref? leafref +--rw passive-device* [id] +--rw id string +--ro uuid? yang:uuid +--rw name? string +--rw description? string +--rw alias? string +--rw device-type? identityref +--rw custom-tags* string +--rw location-ref? nil:ni-location-ref +--rw passive-port* [id] +--rw id string +--ro uuid? yang:uuid +--rw name? string +--rw description? string +--rw alias? string +--rw port-type? identityref +--rw fiber-core-num? uint32 Figure 1: Tree diagram for passive network inventory 5. YANG Modules 5.1. YANG Data Model for Passive Device Inventory Yu, et al. Expires 25 April 2025 [Page 6] Internet-Draft Passive Network Inventory YANG Model October 2024 file "ietf-ni-passive-device@2024-10-21.yang" module ietf-ni-passive-device { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-ni-passive-device"; prefix ni-passive; import ietf-network-inventory { prefix ni; reference "RFCXXXX: A YANG Data Model for Network Inventory"; //RFC Editor: replace XXXX with actual RFC number //and remove this note } import ietf-ni-location { prefix nil; reference "RFCYYYY: A YANG Data Model for Network Inventory Location"; //RFC Editor: replace YYYY with actual RFC number //and remove this note } organization "IETF Network Inventory YANG (ivy) Working Group"; contact "WG Web: WG List: Editor: Chaode Yu Editor: Aihua Guo Editor: Italo Busi "; description "This YANG module specifies a data model for passive devices, such as fibers, cables, and passive sites, deployed within and between network elements. The model fully conforms to the Network Management Datastore Architecture (NMDA). 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 Yu, et al. Expires 25 April 2025 [Page 7] Internet-Draft Passive Network Inventory YANG Model October 2024 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 (https://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX; 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."; // RFC Ed.: replace XXXX with actual RFC number and remove this // note. // RFC Ed.: update the date below with the date of RFC publication // and remove this note. revision 2024-10-21 { description "Initial version"; reference "RFC XXXX: A YANG Data Model for Passive Device Info in Network Inventory."; //RFC Editor: replace XXXX with actual RFC number, update date //information and remove this note } /* Identities */ identity fiber-type { description "Base identity for fiber types."; } identity G652A { base fiber-type; description "ITU-T G.652A fiber."; } identity G652B { base fiber-type; description "ITU-T G.652B fiber."; } identity G652C { base fiber-type; description Yu, et al. Expires 25 April 2025 [Page 8] Internet-Draft Passive Network Inventory YANG Model October 2024 "ITU-T G.652C fiber."; } identity G652D { base fiber-type; description "ITU-T G.652D fiber."; } identity G653 { base fiber-type; description "ITU-T G.653 fiber."; } identity G654 { base fiber-type; description "ITU-T G.654 fiber."; } identity G655 { base fiber-type; description "ITU-T G.655 fiber."; } identity G656 { base fiber-type; description "ITU-T G.656 fiber."; } identity G657A1 { base fiber-type; description "ITU-T G.657A1 fiber."; } identity G657A2 { base fiber-type; description "ITU-T G.657A2 fiber."; } identity G657B { base fiber-type; description "ITU-T G.657B fiber."; } identity other { base fiber-type; description "Other type of fiber."; } Yu, et al. Expires 25 April 2025 [Page 9] Internet-Draft Passive Network Inventory YANG Model October 2024 identity cable-type { description "Base identity for cable types."; } identity backbone { base cable-type; description "Backbone cable."; } identity aggregation { base cable-type; description "Aggregation cable."; } identity access { base cable-type; description "Access cable."; } identity trunk { base cable-type; description "Trunk cable."; } identity distribution { base cable-type; description "Distribution cable."; } identity branch { base cable-type; description "Branch cable."; } identity passive-port-type { description "Base identity for passive port types."; } identity service-port { base passive-port-type; description "Service port."; } identity input-port { base passive-port-type; description "Input port."; Yu, et al. Expires 25 April 2025 [Page 10] Internet-Draft Passive Network Inventory YANG Model October 2024 } identity output-port { base passive-port-type; description "Output port."; } identity p2mp-port { base passive-port-type; description "Input port."; } identity connected-device-type { description "Base identity for connected device types."; } identity passive-device { base connected-device-type; description "Passive/unmanaged device."; } identity active-device { base connected-device-type; description "Active device, e.g. network element."; } identity passive-device-type { description "Base identity for passive device types."; } identity ODF { base passive-device-type; description "Optical Distribution Frame."; } identity WDM { base passive-device-type; description "Wavelength Division Multiplexer."; } identity FAT { base passive-device-type; description "Fiber Access Terminal."; } identity FDT { base passive-device-type; Yu, et al. Expires 25 April 2025 [Page 11] Internet-Draft Passive Network Inventory YANG Model October 2024 description "Fiber Distribution Terminal."; } identity ATB { base passive-device-type; description "Access Terminal Box."; } /* Groupings */ grouping connected-device-end { description "Attributes applicable to connected device end."; leaf device-type { type identityref { base connected-device-type; } description "Type of connected device."; } choice connected-device-type { description "Device end based on the type of connected device."; case passive { leaf device-id { type string; must "derived-from-or-self(../device-type, 'ni-passive:passive-device')"; description "Connected passive device identifier."; } } case active { leaf ne-ref { type leafref { path "/ni:network-inventory/ni:network-elements" + "/ni:network-element/ni:ne-id"; } must "derived-from-or-self(../device-type, 'ni-passive:active-device')"; description "Referenced Network Element (NE)."; } leaf component-ref { type leafref { path "/ni:network-inventory/ni:network-elements" Yu, et al. Expires 25 April 2025 [Page 12] Internet-Draft Passive Network Inventory YANG Model October 2024 + "/ni:network-element[ni:ne-id=current()/.." + "/ne-ref]/ni:components/ni:component" + "/ni:component-id"; } must "derived-from-or-self(../device-type, 'ni-passive:active-device')"; description "Referenced connected active device's component, e.g. port component."; } } } } grouping connected-device-ref { description "Attributes applicable to connected devices."; container a-end { description "A-end device reference"; uses connected-device-end; } container z-end { description "Z-end device reference"; uses connected-device-end; } } grouping optical-cable-segments { description "Attributes applicable to optical fiber cable segments."; list optical-cable-segment { key "id"; min-elements 1; description "List of optical fiber cable segments."; leaf id { type string; description "Cable segment identifier."; } uses ni:common-entity-attributes; leaf fiber-core-num { type uint32; Yu, et al. Expires 25 April 2025 [Page 13] Internet-Draft Passive Network Inventory YANG Model October 2024 description "Number of fiber cores within the cable."; } leaf fiber-type { type identityref { base fiber-type; } description "Type of fiber contained in the cable."; } leaf length { type uint32; units "meter"; description "Length of the cable in meter."; } leaf attenuation { type decimal64 { fraction-digits 2; } units "dB"; description "The fiber attenuation in dB."; } leaf serial-num { type string; description "The serial number of the cable."; } leaf mfg-name { type string; description "The name of the manufacturer of the cable."; } leaf part-number { type string; description "The vendor-specific part number of the cable."; } uses connected-device-ref; } } grouping optical-cables { description "Attributes applicable to optical fiber cables."; list optical-cable { Yu, et al. Expires 25 April 2025 [Page 14] Internet-Draft Passive Network Inventory YANG Model October 2024 key "id"; description "List of optical fiber cables."; leaf id { type string; description "Cable identifier."; } uses ni:common-entity-attributes; leaf cable-type { type identityref { base cable-type; } description "Type of cable."; } leaf fiber-core-num { type uint32; description "Number of fiber cores within the cable."; } uses connected-device-ref; uses optical-cable-segments; } } grouping passive-device-ports { description "Attributes applicable to passive device ports."; list passive-port { key "id"; description "List of ports on a passive device."; leaf id { type string; description "Port identifier."; } uses ni:common-entity-attributes; leaf port-type { type identityref { base passive-port-type; } description "Type of passive port."; Yu, et al. Expires 25 April 2025 [Page 15] Internet-Draft Passive Network Inventory YANG Model October 2024 } leaf fiber-core-num { type uint32; description "Number of fiber cores within the port."; } } } grouping passive-devices { description "Attributes applicable to passive devices."; list passive-device { key "id"; description "List of passive devices."; leaf id { type string; description "Cable identifier."; } uses ni:common-entity-attributes; leaf device-type { type identityref { base passive-device-type; } description "Type of passive device."; } leaf-list custom-tags { type string; description "Customized tags, e.g. RFID, QR code that are attached to the device."; } leaf location-ref { type nil:ni-location-ref; description "Referenced location for the passive device."; } uses passive-device-ports; } } /* Augmentation */ augment "/ni:network-inventory" { Yu, et al. Expires 25 April 2025 [Page 16] Internet-Draft Passive Network Inventory YANG Model October 2024 description "Augment network inventory with information for optical cables and passive devices."; uses optical-cables; uses passive-devices; } } Figure 2: YANG model for passive network inventory 6. Manageability Considerations TBD. 7. Security Considerations The YANG module specified in this document defines a schema for data that is designed to be accessed via network management protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446]. The NETCONF access control model [RFC8341] provides the means to restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. There are a number of data nodes defined in this YANG module that are writable/creatable/deletable (i.e., config true, which is the default). These data nodes may be considered sensitive or vulnerable in some network environments. Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. Considerations in Section 8 of [RFC8795] are also applicable to their subtrees in the module defined in this document. Some of the readable data nodes in this YANG module may be considered sensitive or vulnerable in some network environments. It is thus important to control read access (e.g., via get, get-config, or notification) to these data nodes. Considerations in Section 8 of [RFC8795] are also applicable to their subtrees in the module defined in this document. Yu, et al. Expires 25 April 2025 [Page 17] Internet-Draft Passive Network Inventory YANG Model October 2024 8. IANA Considerations It is proposed to IANA to assign new URIs from the "IETF XML Registry" [RFC3688] as follows: URI: urn:ietf:params:xml:ns:yang:ietf-ni-passive-device Registrant Contact: The IESG XML: N/A; the requested URI is an XML namespace. This document registers the following YANG module in the YANG Module Names registry [RFC6020]. name: ietf-ni-passive-device namespace: urn:ietf:params:xml:ns:yang:ietf-ni-passive-device prefix: ni-passive reference: RFC XXXX 9. Normative References [I-D.draft-ietf-ivy-network-inventory-location] Wu, B., Belotti, S., Bouquier, J., Peruzzini, F., and P. Bedard, "A YANG Data Model for Network Inventory Location", Work in Progress, Internet-Draft, draft-ietf- ivy-network-inventory-location-00, 9 October 2024, . [I-D.draft-ietf-ivy-network-inventory-yang] Yu, C., Belotti, S., Bouquier, J., Peruzzini, F., and P. Bedard, "A YANG Data Model for Network Inventory", Work in Progress, Internet-Draft, draft-ietf-ivy-network- inventory-yang-03, 7 July 2024, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . Yu, et al. Expires 25 April 2025 [Page 18] Internet-Draft Passive Network Inventory YANG Model October 2024 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, . [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, . [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A YANG Data Model for Hardware Management", RFC 8348, DOI 10.17487/RFC8348, March 2018, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . [RFC8453] Ceccarelli, D., Ed. and Y. Lee, Ed., "Framework for Abstraction and Control of TE Networks (ACTN)", RFC 8453, DOI 10.17487/RFC8453, August 2018, . Yu, et al. Expires 25 April 2025 [Page 19] Internet-Draft Passive Network Inventory YANG Model October 2024 [RFC8795] Liu, X., Bryskin, I., Beeram, V., Saad, T., Shah, H., and O. Gonzalez de Dios, "YANG Data Model for Traffic Engineering (TE) Topologies", RFC 8795, DOI 10.17487/RFC8795, August 2020, . Authors' Addresses Chaode Yu Huawei Email: yuchaode@huawei.com Aihua Guo Futurewei Email: aihuaguo.ietf@gmail.com Italo Busi Huawei Email: italo.busi@huawei.com Yu, et al. Expires 25 April 2025 [Page 20]