RFC 8525 YANG Library

Internet Engineering Task Force (IETF)                        A. Bierman
Request for Comments: 8525                                     YumaWorks
Obsoletes: 7895                                             M. Bjorklund
Category: Standards Track                                 Tail-f Systems
ISSN: 2070-1721                                         J. Schoenwaelder
                                                       Jacobs University
                                                               K. Watsen
                                                         Watsen Networks
                                                               R. Wilton
                                                           Cisco Systems
                                                              March 2019

YANG Library

Библиотека YANG

PDF

Аннотация

Этот документ описывает библиотеку YANG, которая обеспечивает информацию обо всех модулях YANG, хранилищах данных и их схемах, применяемых сервером сетевого управления. Обеспечиваемые простые механизмы кэширования позволяют клиентам минимизировать усилия при поиске информации. Данная версия библиотеки YANG поддерживает архитектуру NMDA1 путем перечисления всех хранилищ, поддерживаемых сервером управления и схем, применяемых в каждом из этих хранилищ.

Данный документ отменяет RFC 7895.

Статус документа

Документ относится к категории Internet Standards Track.

Документ является результатом работы IETF2 и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG3. Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 7841.

Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc8525.

Авторские права

Авторские права (Copyright (c) 2019) принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.

К документу применимы права и ограничения, указанные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с упрощённой лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Simplified BSD License).

1. Введение

Нужны стандартные механизмы для идентификации модулей YANG [RFC7950], хранилищ данных [RFC8342] и схем хранилищ [RFC8342] применяемых сервером сетевого управления. Данный документ описывает модуль YANG ietf-yang-library, который обеспечивает эту информацию. Эта версия библиотеки YANG совместима с архитектурой хранилищ NMDA [RFC8342]. Предыдущая версия библиотеки YANG, определённая в [RFC7895], не совместима с NMDA, поскольку предполагает применение во всех хранилищах одной схемы. Это может не соблюдаться в NMDA, где динамические хранилища конфигурации могут применять свои схемы. Кроме того, хранилище рабочего состояния может поддерживать ненастраиваемые модули YANG в дополнение к модулям, поддерживаемым традиционными хранилищами конфигурации.

Определения старой библиотеки YANG сохранены (для совместимости), но отмечены как deprecated (устаревшие). Для совместимости с прежними версиями серверам с поддержкой NMDA следует заполнять устаревшее дерево /modules-state в соответствии со старой версией. Новое дерево /yang-library будет игнорироваться старыми клиентами, но обеспечит все данные, требуемые поддерживающим NMDA клиентам (они будут игнорировать дерево /modules-state). При заполнении /modules-state рекомендуется указывать модули YANG с узлами данных config true, которые могут настраиваться через традиционные хранилища конфигурации, и модули YANG с узлами config false, которые возвращаются операцией NETCONF4 <get> или ее эквивалентом.

Информация библиотеки YANG может различаться на каждом сервере и может меняться в процессе работы или при перезагрузке сервера. Если сервер поддерживает множество протоколов сетевого управления для доступа к хранилищам данных, каждый такой протокол может иметь свой концептуальный экземпляр библиотеки YANG.

Если сервер использует множество модулей YANG, библиотека YANG может быть достаточно велика. Поскольку содержимое библиотеки YANG меняется очень редко, важна возможность клиентов кэшировать это содержимое и определять устаревшие данные кэша.

1.1. Терминология

Ключевые слова необходимо (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.

Перечисленные ниже термины определены в [RFC7950]:

  • module – модуль;

  • submodule – субмодуль;

  • data node – узел данных.

В документе фраза «реализует модуль» (implement a module) применяется в трактовке параграфа 5.6.5 [RFC7950].

Перечисленные ниже термины определены в [RFC8342]:

  • datastore – хранилище данных;

  • datastore schema – схема хранилища данных;

  • configuration – конфигурация;

  • conventional configuration datastore – традиционное хранилище данных;

  • operational state – рабочее состояние;

  • operational state datastore – хранилище рабочего состояния;

  • dynamic configuration datastore – динамическое хранилище конфигурации;

  • client – клиент;

  • server – сервер.

Ниже определены термины, используемые в этом документе.

YANG library – библиотека YANG

Набор модулей и субмодулей YANG, хранилищ и схем хранилищ, применяемых сервером.

YANG library content identifier – идентификатор содержимого библиотеки YANG

Генерируемый сервером идентификатор содержимого библиотеки YANG.

В диаграммах деревьев данный документ использует обозначения, определённые в [RFC8340].

2. Постановка задачи

Приведённая ниже информация нужна клиентскому приложению (для каждого модуля YANG в библиотеке) для полного использования языка моделирования данных YANG:

  • name – имя модуля YANG;

  • revision – при наличии этой информации в модуле или субмодуле YANG номер выпуска берётся из наиболее свежего оператора revision в модуле или субмодуле;

  • submodule list – имя и (при наличии) выпуск каждого субмодуля, используемого модулем;

  • feature list – имя каждой функции (возможности) YANG, поддерживаемой сервером;

  • deviation list – имя каждого модуля YANG с оператором deviation, влияющим на данный модуль YANG.

В дополнение к этому для каждого поддерживаемого сервером хранилища данных клиентскому приложению нужно:

  • identity – отождествление YANG для хранилища данных;

  • schema – схема (т. е. набор модулей), реализованная в хранилище.

Для выбора одного из вариантов модели данных библиотеки YANG использованы приведённые ниже критерии.

  1. Информация должна быть удобна для потребителя. Поскольку библиотека YANG может быть велика, следует позволять клиентам кэшировать содержимое библиотеки YANG.

  2. Динамические хранилища конфигурации должны быть способны реализовать модули или функции, недоступные в традиционных хранилищах конфигурации.

  3. Можно не реализовать функцию или модуль в <operational>, даже если это реализовано в другом хранилище. Это требуется для переходного процесса – сервер, желающий реализовать <operational>, не обязан поддерживать все модули сразу.

  4. Для данного модуля во всех хранилищах может быть реализован лишь один выпуск. Если модуль реализован в нескольких хранилищах, все они должны использовать один выпуск.

  5. Может использоваться множество выпусков для импорта, если применяется импорт по выпуску.

  6. Должна обеспечиваться возможность использования библиотеки YANG при монтировании схемы [RFC8528].

3. Модель данных библиотеки YANG

Модуль ietf-yang-library предоставляет информацию о модулях, субмодулях, хранилищах и схемах хранилищ, поддерживаемых сервером. Все узлы данных модуля ietf-yang-library имеют тип config false и поэтому доступны лишь в хранилище рабочего состояния.

+-----------+
| хранилище |
+-----------+
     |
     | имеет
     V
+-----------+            +--------+                +------------+
|   схема   |объединение | набор  |  состоит из    | модули +   |
| хранилища |----------->| модулей|--------------->| субмодули  |
+-----------+            +--------+                +------------+

Рисунок 1.


Концептуальная модель библиотеки YANG показана на рисунке 1. В соответствии с NMDA каждое хранилище имеет связанную с ним схему, являющуюся объединением наборов модулей, а каждый набор – это коллекция модулей и субмодулей, включая модули и субмодули, служащие для импорта. Отметим, что одна схема может применяться несколькими хранилищами. Кроме того, отдельные схемы хранилищ могут совместно использовать наборы модулей. Общим примером служит хранилище рабочего состояния, которое является надмножеством схемы, применяемой традиционными хранилищами конфигурации.

Ниже приведена диаграмма дерева YANG для модуля ietf-yang-library без устаревшего дерева /modules-state.

   module: ietf-yang-library
     +--ro yang-library
        +--ro module-set* [name]
        |  +--ro name                  string
        |  +--ro module* [name]
        |  |  +--ro name         yang:yang-identifier
        |  |  +--ro revision?    revision-identifier
        |  |  +--ro namespace    inet:uri
        |  |  +--ro location*    inet:uri
        |  |  +--ro submodule* [name]
        |  |  |  +--ro name        yang:yang-identifier
        |  |  |  +--ro revision?   revision-identifier
        |  |  |  +--ro location*   inet:uri
        |  |  +--ro feature*     yang:yang-identifier
        |  |  +--ro deviation*   -> ../../module/name
        |  +--ro import-only-module* [name revision]
        |     +--ro name         yang:yang-identifier
        |     +--ro revision     union
        |     +--ro namespace    inet:uri
        |     +--ro location*    inet:uri
        |     +--ro submodule* [name]
        |        +--ro name        yang:yang-identifier
        |        +--ro revision?   revision-identifier
        |        +--ro location*   inet:uri
        +--ro schema* [name]
        |  +--ro name          string
        |  +--ro module-set*   -> ../../module-set/name
        +--ro datastore* [name]
        |  +--ro name      ds:datastore-ref
        |  +--ro schema    -> ../../schema/name
        +--ro content-id    string
     notifications:
       +---n yang-library-update
          +--ro content-id    -> /yang-library/content-id

Контейнер /yang-library содержит всю библиотеку YANG и имеет перечисленные ниже дочерние узлы.

  • /yang-library/module-set содержит записи, представляющие наборы модулей. Список /yang-library/module-set/module перечисляет все модули, относящиеся к набору. Модуль указывается вместе с субмодулями (если они имеются), набором функций и всеми отклонениями. Список /yang-library/module-set/import-only-module содержит все модули (и их субмодули), используемые лишь для импорта. Назначение модуля в набор определяется сервером. Данный выпуск библиотеки YANG не задаёт семантики включения модуля в список набора.

  • Список /yang-library/schema содержит записи для каждой схемы хранилища, поддерживаемой сервером. Все традиционные хранилища данных используют общую запись списка schema. Динамическое хранилище конфигурации может использовать другую схему и для него может потребоваться отдельная запись в списке schema. Запись имеет лист-список (leaf-list) ссылок на записи в списке module-set. Схема является объединением всех модулей во всех указанных наборах.

  • Список /yang-library/datastore содержит одну запись для каждого хранилища, поддерживаемого сервером, и указывает связанную с хранилищем схему путём ссылки на запись списка schema. Каждое поддерживаемое традиционное хранилище имеет свою запись, указывающую на общий элемент списка schema.

  • Лист /yang-library/content-id содержит идентификатор содержимого библиотеки YANG, зависящий от реализации, который представляет текущие данные в библиотеке YANG на конкретном сервере. Значение этого листа должно меняться при любом изменении информации в библиотеке YANG. Не требуется совпадение content-id для одной и той же информации. Этот лист позволяет клиентам извлекать сразу всю информацию схемы, кэшировать ее и запрашивать снова лишь при изменении листа. Если этот лист меняется, сервер также генерирует уведомление yang-library-update.

Отметим, что для серверов NETCONF, реализующих расширения NETCONF для поддержки NMDA [RFC8526], изменение идентификатора содержимого библиотеки YANG приводит к новому значению возможности :yang-library:1.1, определённой в [RFC8526]. Если такой сервер реализует уведомления NETCONF [RFC5277] и генерируются уведомления netconf-capability-change [RFC6470], такие уведомления будут создаваться при каждой смене идентификатора содержимого библиотеки YANG.

4. Модуль библиотеки YANG

Модуль YANG ietf-yang-library импортирует определения из модулей ietf-yang-types и ietf-inet-types, определённых в [RFC6991], а также из модуля ietf-datastores, определённого в [RFC8342]. Хотя модуль YANG определён с использованием YANG версии 1.1, библиотека YANG поддерживает модули YANG для любой версии языка YANG.

   <CODE BEGINS> file "ietf-yang-library@2019-01-04.yang"

   module ietf-yang-library {
     yang-version 1.1;
     namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library";
     prefix yanglib;

     import ietf-yang-types {
       prefix yang;
       reference
         "RFC 6991: Common YANG Data Types";
     }
     import ietf-inet-types {
       prefix inet;
       reference
         "RFC 6991: Common YANG Data Types";
     }
     import ietf-datastores {
       prefix ds;
       reference
         "RFC 8342: Network Management Datastore Architecture
                    (NMDA)";
     }

     organization
       "IETF NETCONF (Network Configuration) Working Group";
     contact
       "WG Web:   <https://datatracker.ietf.org/wg/netconf/> 
        WG List:  <mailto:netconf@ietf.org> 

        Author:   Andy Bierman
                  <mailto:andy@yumaworks.com> 

        Author:   Martin Bjorklund
                  <mailto:mbj@tail-f.com> 

        Author:   Juergen Schoenwaelder
                  <mailto:j.schoenwaelder@jacobs-university.de> 

        Author:   Kent Watsen
                  <mailto:kent+ietf@watsen.net> 

        Author:   Robert Wilton
                  <mailto:rwilton@cisco.com>"; 
     description
       "Этот модуль содержит информацию о модулях YANG, хранилищах и
        схемах хранилищ, используемых сервером сетевого управления.

        Ключевые слова ДОЛЖНО, НЕДОПУСТИМО, ТРЕБУЕТСЯ, НУЖНО, НЕ СЛЕДУЕТ, 
        СЛЕДУЕТ, НЕ НУЖНО, РЕКОМЕНДУЕТСЯ, НЕ РЕКОМЕНДУЕТСЯ, МОЖНО и
        НЕОБЯЗАТЕЛЬНО в этом документе интерпретируются в соответствии с
        BCP 14 (RFC 2119) (RFC 8174) тогда и только тогда, когда они
        указаны заглавными буквами, как показано здесь.

        Авторские права (Copyright (c) 2019) принадлежат IETF Trust и 
        лицам, указанным как авторы. Все права защищены.

        Распространение и использование в исходной или двоичной форме
        с изменениями или без таковых разрешено в соответствии с 
        упрощённой лицензией BSD, как указано в параграфе 4.c
        документа IETF Trust Legal Provisions применительно к 
        документам IETF (https://trustee.ietf.org/license-info). 

        Данная версия модуля YANG является частью RFC 8525, где
        правовые аспекты изложены более полно.";

     revision 2019-01-04 {
       description
         "Добавлена поддержка хранилищ данных с архитектурой NMDA.";
       reference
         "RFC 8525: YANG Library";
     }
     revision 2016-04-09 {
       description
         "Исходный выпуск.";
       reference
         "RFC 7895: YANG Module Library";
     }

     /*
      * Определения типов
      */

     typedef revision-identifier {
       type string {
         pattern '\d{4}-\d{2}-\d{2}';
       }
       description
         "Представляет дату в формате ГГГГ-ММ-ЧЧ format.";
     }

     /*
      * Группировки
      */

     grouping module-identification-leafs {
       description
         "Параметры для идентификации модулей и субмодулей YANG.";
       leaf name {
         type yang:yang-identifier;
         mandatory true;
         description
           "Имя модуля или субмодуля YANG.";
       }
       leaf revision {
         type revision-identifier;
         description
           "Дата выпуска модуля или субмодуля YANG. Если оператора revision
            нет в модуле или субмодуле YANG, этот лист не создаётся.";
       }
     }

     grouping location-leaf-list {
       description
         "Общий параметр leaf-list для местоположения модулей и субмодулей.";
       leaf-list location {
         type inet:uri;
         description
           "Содержит идентификатор URL, представляющий ресурс схемы YANG 
            для модуля или субмодуля.

            Этот лист присутствует лишь при наличии URL для извлечения
            схемы для данной записи.";
       }
     }

     grouping module-implementation-parameters {
       description
         "Параметры для описания реализации модуля.";
       leaf-list feature {
         type yang:yang-identifier;
         description
           "Список имён всех возможностей YANG из данного модуля, 
            поддерживаемых сервером, независимо от их определения
            в модуле или включённом в него субмодуле.";
       }
       leaf-list deviation {
         type leafref {
           path "../../module/name";
         }
         description
           "Список всем модулей отклонения YANG, используемых сервером,
            для изменения соответствия модуля, связанного с этой записью.
            Отметим, что один и тот же модуль может служить для отклонений
            разных модулей, поэтому одна запись МОЖЕТ присутствовать в 
            нескольких записях module.

            Этой ссылке НЕДОПУСТИМО указывать (напрямую или косвенно)
            модуль без отклонений (deviation).

            Отказоустойчивые клиенты могут захотеть проверить обработку
            ситуаций, где модуль имеет отклонения (напрямую или косвенно).";
       }
     }

     grouping module-set-parameters {
       description
         "Набор параметров, описывающих набор модулей.";
       leaf name {
         type string;
         description
           "Произвольное имя набора модулей.";
       }
       list module {
         key "name";
         description
           "Запись этого списка представляет модуль, реализованный сервером,
            как описано в параграфе 5.6.5 RFC 7950, с конкретным набором
            поддерживаемых возможностей и отклонений.";
         reference
           "RFC 7950: The YANG 1.1 Data Modeling Language";
         uses module-identification-leafs;
         leaf namespace {
           type inet:uri;
           mandatory true;
           description
             "Идентификатор пространства имён XML для этого модуля.";
         }
         uses location-leaf-list;
         list submodule {
           key "name";
           description
             "Каждая запись представляет один субмодуль в родительском
              модуле.";
           uses module-identification-leafs;
           uses location-leaf-list;
         }
         uses module-implementation-parameters;
       }
       list import-only-module {
         key "name revision";
         description
           "Запись этого списка указывает, что сервер импортирует 
            многократно используемые определения из указанного выпуска
            модуля, но не реализует из этого выпуска каких-либо
            доступных протоколу объектов.

            Для одного модуля МОЖЕТ присутствовать множество записей. 
            Это может быть обусловлено импортом множеством модулей одного
            модуля с указанием разных дат выпуска в операторах revision.";
         leaf name {
           type yang:yang-identifier;
           description
             "Имя модуля YANG.";
         }
         leaf revision {
           type union {
             type revision-identifier;
             type string {
               length "0";
             }
           }
           description
             "Дата выпуска модуля YANG. При отсутствии оператора
              revision в модуле YANG указывается пустая строка.";
         }
         leaf namespace {
           type inet:uri;
           mandatory true;
           description
             "Пространство имён XML для этого модуля.";
         }
         uses location-leaf-list;
         list submodule {
           key "name";
           description
             "Каждая запись представляет один субмодуль в родительском
              модуле.";
           uses module-identification-leafs;
           uses location-leaf-list;
         }
       }
     }
     grouping yang-library-parameters {
       description
         "Структура данных библиотеки YANG представлена как группировка,
          поэтому её можно повторно применять в конфигурации или иных 
          структурах данных мониторинга.";
       list module-set {
         key "name";
         description
           "Набор модулей, который может применяться в одной или 
            нескольких схемах.

            Набор модулей не обязан быть ссылочно полным, т. е он может
            определять модули, содержащие операторы import для модулей
            не включённых в этот набор.";
         uses module-set-parameters;
       }
       list schema {
         key "name";
         description
           "Схема хранилища, которая может применяться одним или
            несколькими хранилищами.

            Схема должна быть действительной и ссылочно полное, т. е.
            она должна включать модули для выполнения всех операторов 
            import во всех модулях, указанных в схеме.";
         leaf name {
           type string;
           description
             "Произвольное имя схемы.";
         }
         leaf-list module-set {
           type leafref {
             path "../../module-set/name";
           }
           description
             "Набор module-set, включённых в схему. Если неимпортируемый
              модуль присутствует в нескольких наборах модулей, выпуск
              модуля и связанные с ним возможности (функции) и 
              отклонения должны быть идентичны.";
         }
       }
       list datastore {
         key "name";
         description
           "Хранилище, поддерживаемое сервером.

            Для каждого хранилища указывается поддерживаемая схема.

            Сервер ДОЛЖЕН создавать в этом списке одну запись для 
            каждого поддерживаемого хранилища. Всем хранилищам с
            одной схемой СЛЕДУЕТ ссылаться на эту схему.";
         leaf name {
           type ds:datastore-ref;
           description
             "Отождествление хранилища данных.";
         }
         leaf schema {
           type leafref {
             path "../../schema/name";
           }
           mandatory true;
           description
             "Ссылка на схему, поддерживаемую хранилищем. Все 
              не импортируемые модули схемы реализуются со связанными
              возможностями и отклонениями.";
         }
       }
     }

     /*
      * Контейнер верхнего уровня
      */

     container yang-library {
       config false;
       description
         "Контейнер, содержащий всю библиотеку YANG данного сервера.";
       uses yang-library-parameters;
       leaf content-id {
         type string;
         mandatory true;
         description
           "Созданный сервером идентификатор содержимого дерева
            /yang-library. Сервер ДОЛЖЕН менять значение этого листа, 
            если представленная в дереве /yang-library информация
            меняется (за исключением смены /yang-library/content-id).";
       }
     }

     /*
      * Уведомления
      */

     notification yang-library-update {
       description
         "Генерируется при любом изменении информации в библиотеке YANG
          на сервере.";
       leaf content-id {
         type leafref {
           path "/yanglib:yang-library/yanglib:content-id";
         }
         mandatory true;
         description
           "Включает идентификатор содержимого библиотеки YANG для
            обновлённого варианта на момент создания уведомления.";
       }
     }

     /*
      * Унаследованные группировки
      */

     grouping module-list {
       status deprecated;
       description
         "Структура данных модуля представлена в форме группировки и
          может многократно применяться в конфигурации или другой
          структуре данных мониторинга.";

       grouping common-leafs {
         status deprecated;
         description
           "Общие параметры модулей и субмодулей YANG.";
         leaf name {
           type yang:yang-identifier;
           status deprecated;
           description
             "Имя модуля или субмодуля YANG.";
         }
         leaf revision {
           type union {
             type revision-identifier;
             type string {
               length "0";
             }
           }
           status deprecated;
           description
             "Дата выпуска модуля или субмодуля YANG. Если оператора
              revision нет в модулей или субмодуле, строка будет пустой.";
         }
       }

       grouping schema-leaf {
         status deprecated;
         description
           "Базовый параметр листа схему для модулей и субмодулей.";
         leaf schema {
           type inet:uri;
           description
             "Содержит идентификатор URL, представляющий ресурс схемы YANG
              для модуля или субмодуля.

              Этот лист присутствует лишь при наличии URL, доступного для
              извлечения схемы для данной записи.";
         }
       }
       list module {
         key "name revision";
         status deprecated;
         description
           "Каждая запись представляет один выпуск модуля, поддерживаемый
            в данный момент сервером.";
         uses common-leafs {
           status deprecated;
         }
         uses schema-leaf {
           status deprecated;
         }
         leaf namespace {
           type inet:uri;
           mandatory true;
           status deprecated;
           description
             "Идентификатор пространства имён XML для этого модуля.";
         }
         leaf-list feature {
           type yang:yang-identifier;
           status deprecated;
           description
             "Список имён свойств YANG из данного модуля, которые 
              поддерживаются сервером, независимо от их определения
              в модуле или любом из включённых субмодулей.";
         }
         list deviation {
           key "name revision";
           status deprecated;
           description
             "Список имён отклонений модулей YANG и выпусков, 
              используемых этим сервером для изменения соответствия
              модуля, связанного с этой записью. Отметим, что один
              и тот же модуль может использоваться для указания 
              отклонений множества модулей, поэтому запись МОЖЕТ
              появляться во множестве записей module.

              Модуль отклонений ДОЛЖЕН присутствовать в списке
              module с тем же именем и выпуском. Значением 
              conformance-type для модуля deviation будет implement.";
           uses common-leafs {
             status deprecated;
           }
         }
         leaf conformance-type {
           type enumeration {
             enum implement {
               description
                 "Показывает, что сервер реализует один или множество 
                  доступных протоколу объектов, определённых в модуле 
                  YANG, указанном этой записью. Это включает операторы 
                  deviation, определённые в модуле.

                  Для модулей YANG версии 1.1 имеется не более одной
                  записи с типом соответствия implement для конкретного
                  имени модуля, поскольку YANG 1.1 требует реализации
                  не более одного выпуска модуля.

                  Для модулей YANG версии 1 НЕ СЛЕДУЕТ включать более
                  одной записи module для конкретного имени модуля.";
             }
             enum import {
               description
                 "Показывает, что сервер импортирует повторно используемые
                  определения из указанного выпуска модуля, но не реализует
                  каких-либо доступных протоколу объектов из этого выпуска.

                  МОЖЕТ существовать множество записей module для одного 
                  имени модуля. Это может возникать в случаях импорта одного
                  модуля множеством других модулей с разными датами выпуска 
                  в операторах import.";
             }
           }
           mandatory true;
           status deprecated;
           description
             "Указывает тип соответствия, заявленного сервером для модуля 
              YANG, указанного этой записью.";
         }
         list submodule {
           key "name revision";
           status deprecated;
           description
             "Каждая запись представляет 1 субмодуль в родительском модуле.";
           uses common-leafs {
             status deprecated;
           }
           uses schema-leaf {
             status deprecated;
           }
         }
       }
     }

     /*
      * Унаследованные узлы данных рабочего состояния
      */

     container modules-state {
       config false;
       status deprecated;
       description
         "Содержит информацию мониторинга модуля YANG.";
       leaf module-set-id {
         type string;
         mandatory true;
         status deprecated;
         description
           "Содержит специфический для сервера идентификатор, который
            представляет текущий набор модулей и субмодулей. Сервер
            ДОЛЖЕН менять значение этого листа при изменении данных,
            представленных экземплярами списков module.";
       }
       uses module-list {
         status deprecated;
       }
     }

     /*
      * Унаследованные уведомления
      */

     notification yang-library-change {
       status deprecated;
       description
         "Генерируется при изменении набора модулей и субмодулей,
          поддерживаемых сервером.";
       leaf module-set-id {
         type leafref {
           path "/yanglib:modules-state/yanglib:module-set-id";
         }
         mandatory true;
         status deprecated;
         description
           "Содержит значение module-set-id, которое представляет
            набор модулей и субмодулей, которые сервер поддерживал в
            момент генерации уведомления.";
       }
     }
   }
   <CODE ENDS>

5. Взаимодействие с IANA

RFC 7895 ранее зарегистрировал один идентификатор URI в реестре IETF XML Registry [RFC3688]. Данный документ перенимает эту запись RFC 7895 и меняет значение Registrant Contact на IESG в соответствии с разделом 4 [RFC3688].

     URI: urn:ietf:params:xml:ns:yang:ietf-yang-library
     Registrant Contact: The IESG.
     XML: N/A, запрошенный URI является пространством имён XML.

Данный документ регистрирует модуль YANG в реестре YANG Module Names [RFC6020]

     name:         ietf-yang-library
     namespace:    urn:ietf:params:xml:ns:yang:ietf-yang-library
     prefix:       yanglib
     reference:    RFC 8525

6. Вопросы безопасности

Модуль YANG, заданный в этом документе, определяет схему данных, предназначенных для доступа с использованием протоколов сетевого управления, таких как NETCONF [RFC6241] или RESTCONF [RFC8040]. Нижним уровнем NETCONF является защищённый транспорт с обязательной реализацией протокола SSH5 [RFC6242]. Нижним уровнем RESTCONF является HTTPS с обязательной реализацией защищённого транспорта TLS [RFC8446].

Модель NACM6 [RFC8341] обеспечивает способы ограничения доступа для конкретных пользователей NETCONF или RESTCONF предопределенным подмножеством протокольных операций NETCONF или RESTCONF и содержимого .

Некоторые из доступных для чтения узлов данных этого модуля YANG могут оказаться чувствительными или уязвимыми в отдельных сетевых средах. Поэтому важно ограничить возможность чтения (например, с помощью get, get-config или notification) таких данных. Ниже указаны деликатные/уязвимые субдеревья и узлы данных.

Ветвь /yang-library библиотеки YANG может помочь атакующему при определении возможностей сервера и известных ошибок реализации. Хотя часть этих сведений доступна всем пользователям через сообщения NETCONF <hello> (или похожие сообщения других протоколов управления), этот модуль YANG может раскрывать дополнительные детали, способные помочь атакующему. Уязвимости сервера могут относиться к конкретным модулям, версиям возможностям или отклонениям. Эта информация включается в каждую запись module. Например, если конкретная операция с определенным узлом данных может приводить к аварии на сервере или значительно снижать его производительность, информация из списка модулей будет помогать атакующему обнаружить серверы с таким дефектом для организации атаки на службы.

7. Литература

7.1. Нормативные документы

[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/info/rfc2119>.

[RFC3688] Mealling, M., “The IETF XML Registry”, BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.

[RFC6020] Bjorklund, M., Ed., “YANG – A Data Modeling Language for the Network Configuration Protocol (NETCONF)”, RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.

[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/info/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/info/rfc6242>.

[RFC6991] Schoenwaelder, J., Ed., “Common YANG Data Types”, RFC 6991, DOI 10.17487/RFC6991, July 2013, <https://www.rfc-editor.org/info/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/info/rfc7950>.

[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, “RESTCONF Protocol”, RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/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/info/rfc8174>.

[RFC8341] Bierman, A. and M. Bjorklund, “Network Configuration Access Control Model”, STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.

[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/info/rfc8342>.

[RFC8446] Rescorla, E., “The Transport Layer Security (TLS) Protocol Version 1.3”, RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.

7.2. Дополнительная литература

[RFC5277] Chisholm, S. and H. Trevino, “NETCONF Event Notifications”, RFC 5277, DOI 10.17487/RFC5277, July 2008, <https://www.rfc-editor.org/info/rfc5277>.

[RFC6470] Bierman, A., “Network Configuration Protocol (NETCONF) Base Notifications”, RFC 6470, DOI 10.17487/RFC6470, February 2012, <https://www.rfc-editor.org/info/rfc6470>.

[RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, “YANG Module Library”, RFC 7895, DOI 10.17487/RFC7895, June 2016, <https://www.rfc-editor.org/info/rfc7895>.

[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/info/rfc8340>.

[RFC8343] Bjorklund, M., “A YANG Data Model for Interface Management”, RFC 8343, DOI 10.17487/RFC8343, March 2018, <https://www.rfc-editor.org/info/rfc8343>.

[RFC8344] Bjorklund, M., “A YANG Data Model for IP Management”, RFC 8344, DOI 10.17487/RFC8344, March 2018, <https://www.rfc-editor.org/info/rfc8344>.

[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/info/rfc8345>.

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

[RFC8349] Lhotka, L., Lindem, A., and Y. Qu, “A YANG Data Model for Routing Management (NMDA Version)”, RFC 8349, DOI 10.17487/RFC8349, March 2018, <https://www.rfc-editor.org/info/rfc8349>.

[RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, “NETCONF Extensions to Support the Network Management Datastore Architecture”, RFC 8526, DOI 10.17487/RFC8526, March 2019, <https://www.rfc-editor.org/info/rfc8526>.

[RFC8528] Bjorklund, M. and L. Lhotka, “YANG Schema Mount”, RFC 8528, DOI 10.17487/RFC8528, March 2019, <https://www.rfc-editor.org/info/rfc8528>.

Приложение A. Отличия от RFC 7895

Ниже перечислены изменения [RFC7895] внесённые этим документом.

  • Название YANG Module Library заменено на YANG Library.

  • Добавлен контейнер верхнего уровня /yang-library, включающий всю библиотеку YANG и обеспечивающий информацию о наборах модулей, схемах и хранилищах данных.

  • Контейнер /modules-state переработан в список /yang-library/module-set.

  • Добавлены списки /yang-library/schema и /yang-library/datastore.

  • Добавлены новые группировки взамен признанных устаревшими.

  • Добавлено уведомление yang-library-update взамен устаревшего yang-library-change.

  • Отменено дерево /modules-state.

  • Отменена группировка /module-list.

  • Отменено уведомление /yang-library-change.

Приложение B. Экземпляр библиотеки YANG для базового сервера

Приведённый ниже пример показывает библиотеку YANG базового сервера, реализующего модули ietf-interfaces [RFC8343] и ietf-ip [RFC8344] в хранилищах <running>, <startup> и <operational>, а также модуль ietf-hardware [RFC8348] в хранилище <operational>.

Некоторые значения листьев разбиты на несколько строк из соображений форматирования.

   <yang-library
       xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"
       xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">

     <module-set>
       <name>config-modules</name>
       <module>
         <name>ietf-interfaces</name>
         <revision>2018-02-20</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-interfaces
         </namespace>
       </module>
       <module>
         <name>ietf-ip</name>
         <revision>2018-02-22</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-ip
         </namespace>
       </module>
       <import-only-module>
         <name>ietf-yang-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>ietf-inet-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
         </namespace>
       </import-only-module>
     </module-set>

     <module-set>
       <name>state-modules</name>
       <module>
         <name>ietf-hardware</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-hardware
         </namespace>
       </module>
       <import-only-module>
         <name>ietf-inet-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>ietf-yang-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>iana-hardware</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:iana-hardware
         </namespace>
       </import-only-module>
     </module-set>

     <schema>
       <name>config-schema</name>
       <module-set>config-modules</module-set>
     </schema>
     <schema>
       <name>state-schema</name>
       <module-set>config-modules</module-set>
       <module-set>state-modules</module-set>
     </schema>

     <datastore>
       <name>ds:startup</name>
       <schema>config-schema</schema>
     </datastore>
     <datastore>
       <name>ds:running</name>
       <schema>config-schema</schema>
     </datastore>
     <datastore>
       <name>ds:operational</name>
       <schema>state-schema</schema>
     </datastore>

     <content-id>75a43df9bd56b92aacc156a2958fbe12312fb285</content-id>
   </yang-library>

Приложение C. Экземпляр библиотеки YANG для расширенного сервера

Приведенный ниже пример расширяет библиотеку из приложения B за счёт использования модулей из [RFC8345] и [RFC8349] для иллюстрации сервера с перечисленными ниже дополнительными возможностями.

  • Имеется модуль с возможностями, поддерживаемыми лишь в хранилище <operational>. Модуль ietf-routing поддерживается в <running>, <startup> и <operational>, а модули multiple-ribs и router-id разрешены лишь в <operational>. Поэтому лист router-id доступен для чтения, но не может быть изменён.

  • Поддерживается динамическое хранилище конфигурации example-ds-ephemeral с модулями ietf-network и ietf-network-topology, настраиваемыми с помощью условного протокола динамического управления конфигурацией.

  • Показан пример связанных с хранилищем отклонений. Модуль example-vendor-hardware-deviations включен в схему для хранилища <operational> с целью удаления узлов данных, которые сервер не может поддерживать.

  • Показано применение наборов модулей (module-set) для совместной организации связанных модулей.

Некоторые значения листьев разбиты на несколько строк из соображений форматирования.

   <yang-library
       xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"
       xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores"
       xmlns:ex-ds-eph="urn:example:ds-ephemeral">

     <module-set>
       <name>config-state-modules</name>
       <module>
         <name>ietf-interfaces</name>
         <revision>2018-02-20</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-interfaces
         </namespace>
       </module>
       <module>
         <name>ietf-ip</name>
         <revision>2018-02-22</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-ip
         </namespace>
       </module>
       <module>
         <name>ietf-routing</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-routing
         </namespace>
       </module>
       <import-only-module>
         <name>ietf-yang-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>ietf-inet-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
         </namespace>
       </import-only-module>
     </module-set>

     <module-set>
       <name>config-only-modules</name>
       <module>
         <name>ietf-routing</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-routing
         </namespace>
       </module>
     </module-set>

     <module-set>
       <name>dynamic-config-state-modules</name>
       <module>
         <name>ietf-network</name>
         <revision>2018-02-26</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-network
         </namespace>
       </module>
       <module>
         <name>ietf-network-topology</name>
         <revision>2018-02-26</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-network-topology
         </namespace>
       </module>
       <import-only-module>
         <name>ietf-inet-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
         </namespace>
       </import-only-module>
     </module-set>

     <module-set>
       <name>state-only-modules</name>
       <module>
         <name>ietf-hardware</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-hardware
         </namespace>
         <deviation>example-vendor-hardware-deviations</deviation>
       </module>
       <module>
         <name>ietf-routing</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-routing
         </namespace>
         <feature>multiple-ribs</feature>
         <feature>router-id</feature>
       </module>
       <module>
         <name>example-vendor-hardware-deviations</name>
         <revision>2018-01-31</revision>
         <namespace>
           urn:example:example-vendor-hardware-deviations
         </namespace>
       </module>
       <import-only-module>
         <name>ietf-inet-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-inet-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>ietf-yang-types</name>
         <revision>2013-07-15</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:ietf-yang-types
         </namespace>
       </import-only-module>
       <import-only-module>
         <name>iana-hardware</name>
         <revision>2018-03-13</revision>
         <namespace>
           urn:ietf:params:xml:ns:yang:iana-hardware
         </namespace>
       </import-only-module>
     </module-set>

     <schema>
       <name>config-schema</name>
       <module-set>config-state-modules</module-set>
       <module-set>config-only-modules</module-set>
     </schema>
     <schema>
       <name>dynamic-config-schema</name>
       <module-set>dynamic-config-state-modules</module-set>
     </schema>
     <schema>
       <name>state-schema</name>
       <module-set>config-state-modules</module-set>
       <module-set>dynamic-config-state-modules</module-set>
       <module-set>state-only-modules</module-set>
     </schema>

     <datastore>
       <name>ds:startup</name>
       <schema>config-schema</schema>
     </datastore>
     <datastore>
       <name>ds:running</name>
       <schema>config-schema</schema>
     </datastore>
     <datastore>
       <name>ex-ds-eph:ds-ephemeral</name>
       <schema>dynamic-config-schema</schema>
     </datastore>
     <datastore>
       <name>ds:operational</name>
       <schema>state-schema</schema>
     </datastore>

     <content-id>14782ab9bd56b92aacc156a2958fbe12312fb285</content-id>
   </yang-library>

Адреса авторов

Andy Bierman

YumaWorks

Email: andy@yumaworks.com

Martin Bjorklund

Tail-f Systems

Email: mbj@tail-f.com

Juergen Schoenwaelder

Jacobs University

Email: j.schoenwaelder@jacobs-university.de

Kent Watsen

Watsen Networks

Email: kent+ietf@watsen.net

Robert Wilton

Cisco Systems

Email: rwilton@cisco.com


Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Network Management Datastore Architecture – архитектура хранилища данных сетевого управления.

2Internet Engineering Task Force – комиссия по решению инженерных задач Internet.

3Internet Engineering Steering Group – комиссия по инженерным разработкам Internet.

4Network Configuration Protocol – протокол настройки конфигурации сети.

5Secure Shell – защищённая оболочка.

6Network Configuration Access Control Model – модель управления доступом к конфигурации.

Запись опубликована в рубрике RFC. Добавьте в закладки постоянную ссылку.