A YANG Data Model for Network Diagnosis by Scheduling Sequences of OAM Tests

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 9 January 2025.¶

Copyright Notice

Copyright (c) 2024 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.¶

Table of Contents

1. Introduction

Operations, Administration, and Maintenance (OAM) tasks are fundamental functionalities of the network management. Given the emerging of data models and their utilization in Service Provider's management, the management of OAM tests represent also an area of interest for operators, which requires to be defined as a data model. OAM functionalities provide the means to identify and isolate faults, measure and report of performance. [RFC5860] defines the three main areas involved in OAM:¶

• Fault management, which allows network operators to quickly identify and isolate faults in the network. The OAM framework defines mechanisms for fault detection and isolation, such as continuity check, link trace, and loopback.¶

• Performance management enables monitoring network performance and diagnosing performance issues (i.e., degradation). Some of the measurements such as frame delay measurement, frame delay variation measurement, and frame loss measurement.¶

• Security management defines mechanisms to protect OAM communications from unauthorized access and tampering.¶

[RFC6428] defines several use cases for OAM tools, including:¶

• Continuity Check: This function verifies that a path exists between two points in a network and that the path is operational.¶

• Loopback: This function allows a device to loop back a received packet back to the sender for diagnostic purposes.¶

• Link Trace: This function allows a network operator to trace a path through a network from one device to another.¶

• Performance Monitoring: This function allows a network operator to monitor the performance of a network and to identify and diagnose performance issues.¶

• Security Management: This function allows a network operator to protect OAM communications from unauthorized access and tampering.¶

• Configuration Management: This function allows a network operator to manage the configuration of network devices.¶

More recently, Incident Management [I-D.ietf-nmop-network-incident-yang] also considers the possibility of incident diagnosis, which can be favoured by dynamic invocation of OAM tests.¶

[RFC8531], [RFC8532] and, [RFC8533] defined YANG models for OAM technologies. On the other hand, [RFC8531] defines a YANG data model for connection-oriented OAM protocols. The main aim of this document is to define a generic YANG data model that can be used to configure, control and monitor connection-oriented OAM protocols such as MPLS-TP OAM, PBB-TE OAM, and G.7713.1 OAM. [RFC8532] provides a generic YANG data model that can be used to configure, control and monitor connectionless OAM protocols such as BFD (Bidirectional Forwarding Detection), LBM (Loopback Messaging) and VCCV (Virtual Circuit Connectivity Verification). [RFC8533] provides a YANG data model that can be used to retrieve information related to OAM protocols such as Bidirectional Forwarding Detection (BFD), Loopback Messaging (LBM) and Virtual Circuit Connectivity Verification (VCCV).¶

[RFC8913] specifies a YANG data model for client and server implementations of the Two-Way Active Measurement Protocol (TWAMP).¶

Previous RFCs defined the parameters required for each of the different tests that are used in network elements today. This document covers how to use OAM for network-wide use cases. Following, some illustrative examples are presented.¶

The YANG data model resulting from this document will conform to the Network Management Datastore Architecture (NMDA) [RFC8342].¶

2. Network-wide OAM Use Cases

3. Modelling the Scheduling of OAM Tests

This document proposes two models: OAM unitary test and OAM test sequence models.¶

module: ietf-oam-unitary-test
  +--rw oam-unitary-tests
     +--rw oam-unitary-test* [name]
        +--rw name                      string
        +--rw (test-type)
        +--rw period-description?       string
        +--rw period-start              yang:date-and-time
        +--rw time-zone-identifier?     sys:timezone-name
        +--rw (period-type)?
        |  +--:(explicit)
        |  |  +--rw period-end?         yang:date-and-time
        |  +--:(duration)
        |     +--rw duration?           duration
        +--rw recurrence-description?   string
        +--rw frequency                 identityref
        +--rw interval?                 uint32
        +--rw unitary-test-status?      enumeration

   +---------+      +----------+      +---------+
+->| planned |----->|configured|----->|  ready  |
|  +---------+      +----------+      +---------+
|      A                 |                |
|      |                 |                V
|      |     +-------+   |          +----------+
|      ------| error |<--+----------| on-going |
|      |     +-------+              +----------+
|      |                                  |
|      V                                  |
|  +---------+      +--------+            |
+--| finished|<-----|  stop  |<------------+
   +---------+      +--------+            |
       A                                  |
       |                                  |
       +----------------------------------+

module: ietf-oam-test-sequence
  +--rw oam-test-sequence
     +--rw test-sequence* [name]
        +--rw name                      string
        +--rw test-ref* [name]
        |  +--rw name             string
        |  +--rw (test-type)
        |  +--rw numexecutions?   uint32
        +--rw period-description?       string
        +--rw period-start              yang:date-and-time
        +--rw time-zone-identifier?     sys:timezone-name
        +--rw (period-type)?
        |  +--:(explicit)
        |  |  +--rw period-end?         yang:date-and-time
        |  +--:(duration)
        |     +--rw duration?           duration
        +--rw recurrence-first
        |  +--rw utc-start-time?   yang:date-and-time
        |  +--rw duration?         uint32
        +--rw (recurrence-bound)?
        |  +--:(until)
        |  |  +--rw utc-until?          yang:date-and-time
        |  +--:(count)
        |     +--rw count?              uint32
        +--rw recurrence-description?   string
        +--rw frequency                 identityref
        +--rw interval?                 uint32
        +--rw test-sequence-status?     enumeration

    +---------+      +----------+      +---------+
 +->| planned |----->|configured|----->|  ready  |
 |  +---------+      +----------+      +---------+
 |    A   A                 |              |
 |    |   |                 |              V
 |    |   |     +-------+   |          +----------+
 |    |   ------| error |<--+----------| on-going |
 |    |         +-------+              +----------+
 |    |                                    |
 |    |                                    |
 | +---------+      +--------+             |
 | | failure |<-----|  stop  |<------------+
 | +---------+      +--------+             |
 |                                         |
 | +---------+                             |
 +-| success |<----------------------------+
   +---------+

4. YANG Data Models for Scheduling OAM Tests

<CODE BEGINS> file ietf-oam-unitary-test@2024-07-05.yang
module ietf-oam-unitary-test {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-oam-unitary-test";
  prefix "oamut";

  // Import OAM models from RFCs RFC8531, RFC8532 and RFC8533

  // reference ietf-netmod-schedule-yang
  import ietf-schedule { prefix "schedule"; }

  organization
    "IETF OPSAWG (Operations and Management Area Working Group)";

  contact
    "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
     WG List:  <mailto:opsawg@ietf.org>
     Author: Luis Miguel Contreras Murillo
          <luismiguel.contrerasmurillo@telefonica.com>
     Author: Victor Lopez
          <victor.lopez@nokia.com>";
  description
    "This module defines the 'ietf-oam-unitary-test' YANG model for
     activation of network diagnosis procedures.

    Copyright (c) 2024 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
      (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.";

  // RFC Ed.: update the date below with the date of RFC
  // publication and remove this note.
  // RFC Ed.: replace XXXX with actual RFC number and remove
  // this note.

  revision "2024-07-05" {
    description
      "Initial version";
    reference
      "RFCXXXX: A YANG Data Model for Network Diagnosis by Scheduling
       Sequences of OAM Tests";
       // Update with the correct RFC number when assigned
  }

  grouping oam-unitary-test {
    description
        "This grouping is defined for OAM unitary test for network
        diagnosis procedures.";

    leaf name {
      type string;
      description
        "Name for the test.";
    }

    choice test-type {
      mandatory true;
      description
        "Choose the type of test.";
        // Import OAM models from RFCs RFC8531, RFC8532 and RFC8533
    }
  }

  container oam-unitary-tests {
    description
      "Container for OAM unitary tests activation for network
      diagnosis procedures.";

    list oam-unitary-test {
      key name;
      description
        "List of OAM unitary tests activation for network diagnosis
        procedures.";

      uses oam-unitary-test;

      uses schedule:period-of-time;

      uses schedule:recurrence;

      leaf unitary-test-status {
        type enumeration {
          enum "planned" {
            description
              "The test is planned.";
          }
          enum "configure" {
            description
              "The test is configured.";
          }
          enum "ready" {
            description
              "The test status is ready.";
          }
          enum "ongoing" {
            description
              "The test is ongoing.";
          }
          enum "stop" {
            description
              "The test is stopped.";
          }
          enum "finish" {
            description
              "The test is finished.";
          }
          enum "error" {
            description
              "The test has an error.";
          }
        }
        description
          "Status of the test.";
      }
    }
  }
}


<CODE ENDS>

<CODE BEGINS> file ietf-oam-test-sequence@2024-07-05.yang

module ietf-oam-test-sequence {
  yang-version 1.1;
  namespace "urn:ietf:params:xml:ns:yang:ietf-oam-test-sequence";
  prefix "oamts";

  import ietf-oam-unitary-test {
    prefix "oamut";
    // Update the reference with the correct RFC number or other
    // reference when assigned
    // reference "RFCXXXX";
  }

  // reference ietf-netmod-schedule-yang
  import ietf-schedule { prefix "schedule"; }

  organization
    "IETF OPSAWG (Operations and Management Area Working Group)";

  contact
    "WG Web:   <https://datatracker.ietf.org/wg/opsawg/>
     WG List:  <mailto:opsawg@ietf.org>
     Author: Luis Miguel Contreras Murillo
          <luismiguel.contrerasmurillo@telefonica.com>
     Author: Victor Lopez
          <victor.lopez@nokia.com>";
  description
    "This module defines the 'oam-unitary-test' YANG model for
    activation of network diagnosis procedures.

    Copyright (c) 2024 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
      (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.";

  // RFC Ed.: update the date below with the date of RFC
  // publication and remove this note.
  // RFC Ed.: replace XXXX with actual RFC number and remove
  // this note.

  revision "2024-07-05" {
    description "Initial version";
    reference "RFCXXXX";
    // Update with the correct RFC number when assigned
  }

  // Data model definition

  container oam-test-sequence {
    description
      "Container for executing a sequence of ietf-oam-unitary-tests
      N times.";

    list test-sequence {
      key "name";
      description "List of test sequences.";

      leaf name {
        type string;
        description "Unique name for the test sequence.";
      }

      list test-ref {
        key "name";
        description "References to the ietf-oam-unitary-tests.";

        uses "oamut:oam-unitary-test";

        leaf numexecutions {
          type uint32;
          default 1;
          description
            "Number of times the test sequence should be
            executed.";
        }
      }

      uses schedule:period-of-time;

      uses schedule:recurrence-utc;

      leaf test-sequence-status {
        type enumeration {
          enum "planned" {
            description
              "The test sequence is planned.";
          }
          enum "configured" {
            description
              "The test sequence is configured.";
          }
          enum "ready" {
            description
              "The test sequence is ready.";
          }
          enum "ongoing" {
            description
              "The test sequence status is ongoing.";
          }
          enum "stop" {
            description
              "The test sequenceis stopped.";
          }
          enum "success" {
            description
              "All tests in the sequence were successful.";
          }
          enum "failure" {
            description
              "One or more tests in the sequence got an error.";
          }
          enum "error" {
            description
              "The test sequence status has an error.";
          }
        }

        description
          "Status of the test sequence execution.";
      }
    }
  }
}


<CODE ENDS>

5. Using Device Mode Within OAM Scheduling Models

This section discusses the problematic of reusing device models already defined in IETF within the context of scheduling OAM tests. There are two main approaches to enable OAM scheduling models: * Importing YANG model into the OAM scheduling models. This approach will copy the device model into the OAM unitary test model to enable the configuration and utilization of the desire OAM test. This approach requires to recreate new YANG models for each new test type or variation of the device models. * Schema-mount allows mounting a data model at a specified location of another (parent) schema. The main difference with importing the YANG modules is that they don't have to be prepared for mounting; any existing modules such as "ietf-twamp" can be mounted without any modifications.¶

As an exmaple, we will use [RFC8913], which defines a YANG data model for TWAMP, to illustrate how device models could be used.¶

6. Security Considerations

The YANG module targeted 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 [RFC5246].¶

The NETCONF access control model [RFC6536] 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.¶

In which refers to the scheduling of the tests, security considerations in [I-D.ietf-netmod-schedule-yang] are also applicable here.¶

7. IANA Considerations

TBC¶

8. Implementation Status

This section will be used to track the status of the implementations of the model. It is aimed at being removed if the document becomes RFC.¶

9. Normative References

[I-D.ietf-netmod-schedule-yang]

Ma, Q., Wu, Q., Boucadair, M., and D. King, "A Common YANG Data Model for Scheduling", Work in Progress, Internet-Draft, draft-ietf-netmod-schedule-yang-02, 25 June 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-netmod-schedule-yang-02>.

[I-D.ietf-nmop-network-incident-yang]

Hu, T., Contreras, L. M., Wu, Q., Davis, N., and C. Feng, "A YANG Data Model for Network Incident Management", Work in Progress, Internet-Draft, draft-ietf-nmop-network-incident-yang-01, 28 June 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-nmop-network-incident-yang-01>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5246]

Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008, <https://www.rfc-editor.org/rfc/rfc5246>.

[RFC5860]

Vigoureux, M., Ed., Ward, D., Ed., and M. Betts, Ed., "Requirements for Operations, Administration, and Maintenance (OAM) in MPLS Transport Networks", RFC 5860, DOI 10.17487/RFC5860, May 2010, <https://www.rfc-editor.org/rfc/rfc5860>.

[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, <https://www.rfc-editor.org/rfc/rfc6241>.

[RFC6242]

Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/rfc/rfc6242>.

[RFC6428]

Allan, D., Ed., Swallow, G., Ed., and J. Drake, Ed., "Proactive Connectivity Verification, Continuity Check, and Remote Defect Indication for the MPLS Transport Profile", RFC 6428, DOI 10.17487/RFC6428, November 2011, <https://www.rfc-editor.org/rfc/rfc6428>.

[RFC6536]

Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, DOI 10.17487/RFC6536, March 2012, <https://www.rfc-editor.org/rfc/rfc6536>.

[RFC6991]

Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/rfc/rfc6991>.

[RFC7950]

Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, <https://www.rfc-editor.org/rfc/rfc7950>.

[RFC8040]

Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/rfc/rfc8040>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8340]

Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, <https://www.rfc-editor.org/rfc/rfc8340>.

[RFC8342]

Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/rfc/rfc8342>.

[RFC8345]

Clemm, A., Medved, J., Varga, R., Bahadur, N., Ananthakrishnan, H., and X. Liu, "A YANG Data Model for Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 2018, <https://www.rfc-editor.org/rfc/rfc8345>.

[RFC8346]

Clemm, A., Medved, J., Varga, R., Liu, X., Ananthakrishnan, H., and N. Bahadur, "A YANG Data Model for Layer 3 Topologies", RFC 8346, DOI 10.17487/RFC8346, March 2018, <https://www.rfc-editor.org/rfc/rfc8346>.

[RFC8531]

Kumar, D., Wu, Q., and Z. Wang, "Generic YANG Data Model for Connection-Oriented Operations, Administration, and Maintenance (OAM) Protocols", RFC 8531, DOI 10.17487/RFC8531, April 2019, <https://www.rfc-editor.org/rfc/rfc8531>.

[RFC8532]

Kumar, D., Wang, Z., Wu, Q., Ed., Rahman, R., and S. Raghavan, "Generic YANG Data Model for the Management of Operations, Administration, and Maintenance (OAM) Protocols That Use Connectionless Communications", RFC 8532, DOI 10.17487/RFC8532, April 2019, <https://www.rfc-editor.org/rfc/rfc8532>.

[RFC8533]

Kumar, D., Wang, M., Wu, Q., Ed., Rahman, R., and S. Raghavan, "A YANG Data Model for Retrieval Methods for the Management of Operations, Administration, and Maintenance (OAM) Protocols That Use Connectionless Communications", RFC 8533, DOI 10.17487/RFC8533, April 2019, <https://www.rfc-editor.org/rfc/rfc8533>.

[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, <https://www.rfc-editor.org/rfc/rfc8795>.

[RFC8913]

Civil, R., Morton, A., Rahman, R., Jethanandani, M., and K. Pentikousis, Ed., "Two-Way Active Measurement Protocol (TWAMP) YANG Data Model", RFC 8913, DOI 10.17487/RFC8913, November 2021, <https://www.rfc-editor.org/rfc/rfc8913>.

Acknowledgments

TODO acknowledge.¶

Authors' Addresses