RFC 7950 The YANG 1.1 Data Modeling Language

Please enter banners and links.

image_print
Internet Engineering Task Force (IETF)                 M. Bjorklund, Ed.
Request for Comments: 7950                                Tail-f Systems
Category: Standards Track                                    August 2016
ISSN: 2070-1721

Язык моделирования данных YANG 1.1

The YANG 1.1 Data Modeling Language

PDF

Тезисы

YANG представляет собой язык моделирования данных, применяемый в моделях конфигурационных данных, данных состояния, вызовов удаленных процедур (RPC1) и уведомлениях для протоколов управления сетями. Этот документ описывает синтаксис и семантику языка YANG версии 1.1. Эта версия устраняет неоднозначности и дефекты, обнаруженные в исходной спецификации языка YANG. Имеется незначительное число несовместимостей с языком YANG версии 1. Документ также задает отображения YANG на протокол управления конфигурацией сети NETCONF2.

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

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

Документ является результатом работы IETF3 и представляет согласованный взгляд сообщества IETF. Документ прошел открытое обсуждение и был одобрен для публикации IESG4. Не все одобренные IESG документы претендуют на статус Internet Standard (см. раздел 2 в RFC 7841).

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

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

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

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

Документ может содержать материалы из IETF Document или IETF Contribution, опубликованных или публично доступных до 10 ноября 2008 года. Лица, контролирующие авторские права на некоторые из таких документов, могли не предоставить IETF Trust права разрешать внесение изменений в такие документы за рамками процессов IETF Standards. Без получения соответствующего разрешения от лиц, контролирующих авторские права этот документ не может быть изменен вне рамок процесса IETF Standards, не могут также создаваться производные документы за рамками процесса IETF Standards за исключением форматирования документа для публикации или перевода с английского языка на другие языки.

Оглавление

Исключено в версии HTML

1. Введение

YANG представляет собой язык моделирования данных, изначально разработанный для работы с конфигурационными параметрами и данными состояния протокола настройки конфигурации сети NETCONF, вызовов удаленных процедур NETCONF RPC и уведомлений NETCONF [RFC6241]. С момента публикации YANG версии 1 [RFC6020] язык применялся или был предложен для использования также в других протоколах (например, RESTCONF [RESTCONF] и CoMI1 [CoMI]). Кроме того, было предложено кодирование, отличающееся от XML (например, JSON [RFC7951]).

В этом документе описывается синтаксис и семантика языка YANG версии 1.1. Описывается также представление модулей YANG на расширяемом языке разметки XML2 [XML] и использование операций NETCONF для манипулирования данными. Возможно использование и других протоколов, но это выходит за рамки спецификации.

В документе [YANG-Guidelines] приведены некоторые рекомендации по разработке моделей данных YANG.

Следует подчеркнуть, что этот документ не отменяет RFC 6020 [RFC6020].

1.1. Основные отличия от RFC 6020

Этот документ определяет версию 1.1 языка YANG, которая исправляет неточности и дефекты исходной спецификации языка YANG [RFC6020].

Ниже перечислены изменения, не совместимые с YANG версии 1.

  • Изменены правила интерпретации escape-символов внутри двойных кавычек. Это изменение не совместимо с YANG версии 1 и при переходе к версии 1.1 модули, использующие непригодные в новой версии последовательности символов, должны быть изменены в соответствии с новыми правилами. Подробности приведены в параграфе 6.1.3.

  • Строки, не заключенные в кавычки, не могут включать символы одинарных или двойных кавычек. Это изменение не совместимо с YANG версии 1 и при переходе к версии 1.1 модули, использующие непригодные в новой версии последовательности символов, должны быть изменены в соответствии с новыми правилами. Подробности приведены в параграфе 6.1.3.

  • Конструкции when и if-feature не применимы в списке ключей. Это изменение не совместимо с YANG версии 1 и при переходе к версии 1.1 модули, использующие непригодные в новой версии конструкции, должны быть удалены в соответствии с новыми правилами.

  • Определены допустимые в модулях YANG символы. При переходе к версии 1.1 все символы, ставшие непригодными, должны быть удалены. Подробности приведены в разделе 6.

  • Запрещено использование несимвольных кодов во встроенном типе string. Это изменение оказывает влияние на работу протоколов на базе YANG.

Ниже перечислены другие изменения, внесенные в язык YANG.

  • Номер версии YANG 1 заменен на 1.1.

  • Оператор yang-version стал обязательным в версии YANG 1.1.

  • Расширен синтаксис if-feature для использования логических выражений с именами функций.

  • Разрешено использовать if-feature в bit, enum и identity.

  • Разрешено использовать if-feature в refine.

  • Разрешено использовать choice в качестве сокращенного оператора case (см. параграф 7.9.2).

  • Добавлен субоператор modifier в оператор pattern (см. параграф 9.4.6).

  • Разрешено использовать must в input, output и notification.

  • Разрешено использовать require-instance в leafref.

  • Разрешено использовать description и reference в import и include.

  • Разрешен импорт множества ревизий модуля.

  • Разрешено использовать augment для добавления условно обязательных узлов (см. параграф 7.17).

  • Добавлен набор функций XPath3 в разделе 10.

  • Уточнен XPath дерева контекста в параграфе 6.4.1.

  • Определено строковое значение identityref в выражениях XPath (см. параграф 9.10).

  • Уточнено значение неожиданных имен в leafrefs определений типов (typedefs) (см. параграфы 6.4.1 и 9.9.2).

  • Разрешено создание идентификационных данных (identity) из множества базовых отождествлений (см. параграфы 7.18 и 9.10).

  • Разрешено применять перечисляемые (enumeration) и биты (bit) в качестве субтипов (см. параграфы 9.6 и 9.7).

  • Разрешены принятые по умолчанию значения leaf-list (см. параграф 7.7.2).

  • Разрешены совпадающие (не уникальные) значения в leaf-list, не относящихся к конфигурации (см. параграф 7.7).

  • В грамматике применяется синтаксис регистро-чувствительных строк (как в [RFC7405]).

  • Изменен механизм анонсирования модулей (см. параграф 5.6.4).

  • Изменены правила области действия для определений в субмодулях. Субмодуль сейчас может указывать на все определения во всех субмодулях, относящихся к тому же модулю, без применения оператора include.

  • Добавлен оператор action, который используется для определения операций, привязанных к узлам данных.

  • Разрешено привязывать уведомления к узлам данных.

  • Добавлен оператор определения данных anydata (см. параграф 7.10), который рекомендуется применять взамен anyxml, когда данные могут моделироваться в YANG.

  • Разрешены типы empty и leafref в объединениях (union).

  • Разрешен тип empty в ключах (key).

  • Удалено ограничение, не позволявшее идентификаторам начинаться с символов xml.

Ниже приведено изменение, внесенное в отображение для протокола NETCONF.

  • Сервер анонсирует поддержку модулей YANG 1.1, используя ietf-yang-library [RFC7895] вместо ее перечисления в списке возможностей сообщения <hello>.

2. Уровни требований

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

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

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

action – действие

Операция, определенная для узла в дереве данных.

anydata – любые данные

Узел данных, который может содержать неизвестный набор узлов, что могут моделироваться языком YANG, за исключением anyxml.

anyxml – любые данные XML

Узел данных, который может содержать любой неизвестный блок (chunk) данных XML.

augment – дополнение

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

base type – базовый тип

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

built-in type – встроенный тип

Тип данных YANG, определенный в самом языке YANG (например, uint32 или string).

choice – выбор

Узел схемы, где действует лишь один из указанных вариантов.

client – клиент

Объект, который может иметь доступ к определенным YANG данным на сервер с использованием того или иного сетевого протокола.

conformance – соответствие,

Степень точности соблюдения сервером модели данных.

container – контейнер

Внутренний узел данных, существующий в дереве не более чем в одном экземпляре. Контейнер не имеет значения, а имеет набор дочерних узлов.

data definition statement – оператор определения данных

Оператор, определяющий новые узлы данных. Один из операторов container, leaf, leaf-list, list, choice, case, augment, uses, anydata и anyxml.

data model – модель данных

Модель данных описывает представление данных и доступ к ним.

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

Узел в дереве схемы, который может быть помещен в дерево данных. Один из container, leaf, leaf-list, list, anydata и anyxml.

data tree – дерево данных

Воплощенное дерево любых данных, промоделированных с помощью YANG, например, конфигурационные параметры, данные состояния, комбинация данных конфигурации и состояния, входные данные операции или RPC, выходные данные операции или RPC, уведомление.

derived type – производный тип

Тип, определенный на основе встроенного (например, uint32) или другого производного типа.

extension – расширение

Расширение добавляет к операторам не включенную в YANG семантику. Оператор extension определяет новые операторы для выражения этой семантики.

feature – функция, возможность

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

grouping – группировка

Набор многократно используемых (reusable) узлов схемы, который может использоваться локально в модуле или в других модулях, импортирующих его. Оператор grouping не является оператором определения данных, поэтому он не задает каких-либо узлов в дереве схемы.

identifier – идентификатор

Строка, используемая для указания различных элементов YANG по именам.

identity – отождествление

Уникальное в глобальном масштабе, абстрактное и не типизованное имя.

instance identifier – идентификатор экземпляра

Механизм для идентификации конкретных узлов в дереве данных.

interior node – внутренний узел

Узел в иерархии, который не является листом (leaf).

leaf – лист

Узел данных, который существует в дереве данных в количестве не более одного экземпляра. Лист имеет значение, но не имеет дочерних узлов.

leaf-list – лист-список

Похож на лист, но определяет набор однозначно идентифицируемых узлов, а не один узел. Каждый из узлов списка имеет значение, но не имеет узлов-потомков.

list – список

Внутренний узел данных, который может существовать в дереве данных во множестве экземпляров. Список не имеет значения, но имеет набор дочерних узлов.

mandatory node – обязательный узел

Один из перечисленных ниже вариантов:

  • узел leaf, choice, anydata или anyxml с оператором mandatory, имеющим значение true;
  • узел list или leaf-list с оператором min-elements, имеющим значение больше 0;
  • узел container без оператора presence, имеющий в качестве потомка хотя бы один обязательный узел.

module – модуль

Модуль YANG определяет иерархии узлов схемы. Со своими и импортированными или включенными из любого источника определениями модуль является самодостаточным и «компилируемым».

non-presence container — контейнер отсутствия

Контейнер, который не имеет смысла сам по себе и служит только для включения дочерних узлов.

presence container — контейнер присутствия

Контейнер, само присутствие которого имеет некий смысл (значение).

RPC

Вызов удаленной процедуры.

RPC operation — операция RPC

Вызов конкретной удаленной процедуры (RPC).

schema node — узел схемы

Узел в дереве схемы – action, container, leaf, leaf-list, list, choice, case, rpc, input, output, notification, anydata или anyxml.

schema node identifier идентификатор узла схемы

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

schema tree — дерево схемы

Определение иерархии, заданное внутри модуля.

server – сервер

Объект, обеспечивающий клиентам доступ к определенным в YANG данным через тот или иной протокол сетевого управления.

server deviation — отклонение (в поведении) сервера

Отказ сервера реализовать модуль.

submodule – субмодуль

Частичное определение модуля, вносящее производные типы, группировки, узлы данных, RPC, действия и уведомления для модуля. Модуль YANG может содержать множество субмодулей.

top-level data node — узел данных верхнего уровня

Узел данных, не имеющий других узлов данных между собой и оператором module или submodule.

uses – использует

Оператор служит для создания экземпляра множества узлов схемы, определенного в операторе grouping. Создаваемые узлы могут быть уточнены и дополнены в соответствии с конкретными потребностями.

value space — пространство значений

Применительно к типу данных – это набор значений, разрешенных для этого типа. Для экземпляра leaf или leaf-list — пространство значений его типа данных.

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

  • конфигурационные данные (configuration data);

  • конфигурационное хранилище (configuration datastore);

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

  • данные состояния (state data).

При моделировании в YANG хранилище данных реализуется в виде экземпляра дерева данных.

При моделировании в YANG конфигурационное хранилище данных реализуется в виде экземпляра дерева данных с параметрами конфигурации.

3.1. О примерах

В этом документе встречаются многочисленные примеры операторов YANG. Предполагается, что эти примеры будут иллюстрировать отдельные функции, но примеры не являются законченными модулями YANG.

4. Обзор языка YANG

Этот не нормативный раздел содержит ознакомительный обзор языка YANG.

4.1. Функциональный обзор

Язык YANG был разработан для моделирования данных в протоколе NETCONF. Модуль YANG определяет иерархии данных, которые могут применяться в операциях на основе NETCONF, включая параметры конфигурации, данные состояния, RPC и уведомления. Это позволило полностью описать данные, передаваемые между клиентами и серверами NETCONF. Хотя это и выходит за рамки спецификации, YANG можно использовать и с другими протоколами.

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

YANG структурирует модели данных в модули и субмодули. Модуль может импортировать определения из внешних модулей и включать определения из своих субмодулей. Иерархия может дополняться путем позволения модулю добавлять узлы данных в иерархию, определенную в другом модуле. Дополнение может быть условным, когда новые узлы добавляются только при выполнении заданных условий.

Модели данных YANG могут описывать ограничения, применяемые к данным, ограничивая присутствие или значения узлов в зависимости от наличия или значения других узлов в иерархии. Эти ограничения применяются клиентом или сервером.

YANG определяет набор встроенных типов и включает механизм для определения новых типов. Производные типы могут ограничивать набор значений по сравнению с базовым типом, путем применения механизмов типа ограничений на числа элементов или шаблонов (pattern), которые могут применяться клиентами или серверами. Они могут также задавать соглашения по использованию производного типа как, например, основанный на string тип для указания имен хостов.

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

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

Модули YANG могут транслироваться в эквивалентный синтаксис XML, называемый YIN4 (раздел 13), что позволяет приложениям использовать анализаторы XML и сценарии XSLT5 для работы с моделями. Преобразование из YANG в YIN происходит без семантических потерь, поэтому YIN можно обратно преобразовать в YANG.

Язык YANG является расширяемым и позволяет определять расширения органам стандартизации, производителям и отдельным людям. Синтаксис операторов позволяет расширениям естественным образом существовать вместе со стандартными операторами, при этом расширения в модуле YANG достаточно выделяются, чтобы быть заметными.

YANG не пытается решить все возможные задачи, ограничивая область действия выражением моделей данных для протоколов управления сетями типа NETCONF, а не произвольных документов XML или моделей данных.

Насколько это возможно, YANG поддерживает совместимость со структурами SMIv26 [RFC2578] [RFC2579] протокола SNMP7. Основанные на SMIv2 модули MIB могут автоматически преобразовываться в модули YANG с доступом только для чтения (read-only) [RFC6643]. Однако YANG не обеспечивает трансляции в SMIv2.

4.2. Обзор языка

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

4.2.1. Модули и субмодули

Модели данных YANG определяются в модулях. Модуль содержит набор связанных между собой определений.

Модули содержат три типа операторов: операторы заголовка, операторы версии (revision) и операторы определений. Операторы заголовка описывают модуль и дают информацию о самом модуле, операторы revision указывают сведения об развитии модуля, а операторы определений являются телом модуля, где определяется модель данных.

Сервер может поддерживать множество модулей, давая разные представления для одних и тех же данных или набор представлений отдельных подмножеств данных сервера. Сервер может также поддерживать единственный модуль, определяющий все доступные данные.

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

Оператор import позволяет модулю или субмодулю указывать определения из других модулей.

Оператор include используется в модуле для идентификации входящих в него субмодулей.

4.2.2. Основы моделирования данных

YANG определяет четыре основных типа узлов данных для моделирования данных. В каждом из последующих параграфов примеры показывают синтаксис YANG и соответствующее представление XML. Синтаксис операторов YANG определен в параграфе 6.3.

4.2.2.1. Лист

Экземпляр листа (leaf) содержит простые данные типа целого числа или строки. Лист имеет ровно одно значение конкретного типа и не имеет дочерних узлов.

Пример YANG.

     leaf host-name {
       type string;
       description
         "Hostname for this system.";
     }

Пример представления XML.

     <host-name>my.example.com</host-name>

Оператор leaf описан в параграфе 7.6.

4.2.2.2. Список листьев

Список листьев (leaf-list) определяет последовательность значений определенного типа.

Пример YANG.

     leaf-list domain-search {
       type string;
       description
         "List of domain names to search.";
     }

Пример представления XML.

     <domain-search>high.example.com</domain-search>
     <domain-search>low.example.com</domain-search>
     <domain-search>everywhere.example.com</domain-search>

Оператор leaf-list описан в параграфе 7.7.

4.2.2.3. Контейнер

Контейнеры служат для группировки связанных узлов в субдерево (ветвь). Контейнер имеет лишь дочерние узлы и не имеет значения. Контейнер может содержать любое число узлов произвольного типа (листья, списки, контейнеры, листья-списки, действия и уведомления).

Пример YANG.

     container system {
       container login {
         leaf message {
           type string;
           description
             "Message given at start of login session.";
         }
       }
     }

Пример представления XML.

     <system>
       <login>
         <message>Good morning</message>
       </login>
     </system>

Оператор container описан в разделе параграфе 7.5.

4.2.2.4. Список

Список определяет последовательность элементов. Каждый элемент подобен контейнеру и однозначно идентифицируется значениями ключевых листьев, если они определены. Список может определять множество ключевых листьев и включать произвольное число дочерних узлов любого типа (листья, списки, контейнеры и т. п.).

Пример YANG.

     list user {
       key "name";
       leaf name {
         type string;
       }
       leaf full-name {
         type string;
       }
       leaf class {
         type string;
       }
     }

Пример представления XML.

     <user>
       <name>glocks</name>
       <full-name>Goldie Locks</full-name>
       <class>intruder</class>
     </user>
     <user>
       <name>snowey</name>
       <full-name>Snow White</full-name>
       <class>free-loader</class>
     </user>
     <user>
       <name>rzell</name>
       <full-name>Rapun Zell</full-name>
       <class>tower</class>
     </user>

Оператор list описан в параграфе 7.8.

4.2.2.5. Пример модуля

Ниже показан пример комбинации операторов для определения модуля.

     // Содержимое примера example-system.yang
     module example-system {
       yang-version 1.1;
       namespace "urn:example:system";
       prefix "sys";

       organization "Example Inc.";
       contact "joe@example.com";
       description
         "The module for entities implementing the Example system.";

       revision 2007-06-09 {
         description "Initial revision.";
       }

       container system {
         leaf host-name {
           type string;
           description
             "Hostname for this system.";
         }

         leaf-list domain-search {
           type string;
           description
             "List of domain names to search.";
         }

         container login {
           leaf message {
             type string;
             description
               "Message given at start of login session.";
           }

           list user {
             key "name";
             leaf name {
               type string;
             }
             leaf full-name {
               type string;
             }
             leaf class {
               type string;
             }
           }
         }
       }
     }

4.2.3. Данные конфигурации и состояния

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

В приведенном ниже примере для каждого интерфейса определены два узла, определяющие заданную в конфигурации и наблюдаемую скорость.

     list interface {
       key "name";
       config true;

       leaf name {
         type string;
       }
       leaf speed {
         type enumeration {
           enum 10m;
           enum 100m;
           enum auto;
         }
       }
       leaf observed-speed {
         type uint32;
         config false;
       }
     }

Оператор config описан в параграфе 7.21.1.

4.2.4. Встроенные типы

Язык YANG имеет набор встроенных типов, подобно многим языкам программирования, но с некоторыми отличиями, которые связаны со специальными требованиями сетевого управления. В таблице перечислены встроенные типы, которые подробно описаны в разделе 9.

Имя

Описание

binary

произвольные двоичные данные

bits

набор битов или флагов

boolean

true или false

decimal64

64-битовое десятичное число со знаком

empty

лист, не имеющий какого-либо значения

enumeration

одно из перечисляемого набора строковых значений

identityref

ссылка на абстрактное отождествление (identity)

instance-identifier

ссылка на узел дерева данных

int8

8-битовое целое число со знаком

int16

16-битовое целое число со знаком

int32

32-битовое целое число со знаком

int64

64-битовое целое число со знаком

leafref

ссылка на экземпляр листа

string

строка символов

uint8

8-битовое целое число без знака

uint16

16-битовое целое число без знака

uint32

32-битовое целое число без знака

uint64

64-битовое целое число без знака

union

выбор одного из входящих в объединение типов

Оператор type описан в параграфе 7.4.

4.2.5. Производные типы (typedef)

YANG позволяет определять производные (derived) типы на основе базовых с помощью оператора typedef. Базовым типом может быть встроенный или ранее определенный производный тип, что позволяет создавать иерархии производных типов.

Производные типы могут указываться в качестве аргумента операторов type.

Пример YANG.

     typedef percent {
       type uint8 {
         range "0 .. 100";
       }
     }

     leaf completed {
       type percent;
     }

Пример представления XML.

     <completed>20</completed>

Оператор typedef описан в параграфе 7.3.

4.2.6. Многократно используемые группы узлов (grouping)

Группы узлов могут собираться в многократно применяемые наборы и помощью оператора grouping. Группировка определяет множество узлов, которое создается с помощью оператора uses.

Пример YANG

     grouping target {
       leaf address {
         type inet:ip-address;
         description "Target IP address.";
       }
       leaf port {
         type inet:port-number;
          description "Target port number.";
       }
     }

     container peer {
       container destination {
         uses target;
       }
     }

Пример представления XML

     <peer>
       <destination>
         <address>2001:db8::2</address>
         <port>830</port>
       </destination>
     </peer>

Группировка может быть уточнена, что позволяет переопределять в ней некоторые операторы. В приведенном ниже примере уточняется описание (description).

     container connection {
       container source {
         uses target {
           refine "address" {
             description "Source IP address.";
           }
           refine "port" {
             description "Source port number.";
           }
         }
       }
       container destination {
         uses target {
           refine "address" {
             description "Destination IP address.";
           }
           refine "port" {
             description "Destination port number.";
           }
         }
       }
     }

Оператор grouping описан в параграфе 7.12.

4.2.7. Выбор

YANG позволяет модели данных разделять несовместимые узлы в разные варианты с помощью операторов choice и case. Оператор choice содержит набор операторов case, определяющих набор узлов схемы, которые не могут появляться вместе. Каждый case может содержать множество узлов, но каждый узел может появляться только в одном case в рамках оператора choice.

Узлы choice и case появляются только в дереве схемы и не могут присутствовать в дереве данных. Дополнительные уровни иерархии за пределами концептуальной схемы не требуются. Присутствие case указывается наличием одного или множества узлов внутри оператора.

Поскольку в каждый момент может быть приемлем лишь один из вариантов (case) выбора (choice), при создании в дереве данных узла из одного варианта (case), узлы из всех остальных вариантов неявно удаляются. Сервер обеспечивает выполнение этого ограничения, предотвращая от возникновения несовместимостей в конфигурации.

Пример YANG

     container food {
       choice snack {
         case sports-arena {
           leaf pretzel {
             type empty;
           }
           leaf beer {
             type empty;
           }
         }
         case late-night {
           leaf chocolate {
             type enumeration {
               enum dark;
               enum milk;
               enum first-available;
             }
           }
         }
       }
     }

Пример представления XML

     <food>
       <pretzel/>
       <beer/>
     </food>

Оператор choice описан в параграфе 7.9.

4.2.8. Расширение моделей данных (augment)

YANG позволяет вставлять дополнительные узлы в модель данных как текущего модуля (и его субмодулей), так и внешних модулей. Это полезно, например, для производителей, добавляющих свои параметры в стандартные модели данных.

Оператор augment определяет место в иерархии модели данных, куда помещаются новые узлы, а оператор when задает условия, когда новые узлы становятся пригодными (вступают в силу).

Когда сервер реализует модуль с оператором augment, это предполагает, что реализация сервером дополненного модуля включает добавленные узлы.

Пример YANG

     augment /system/login/user {
       when "class != 'wheel'";
       leaf uid {
         type uint16 {
           range "1000 .. 30000";
         }
       }
     }

В этом примере определен узел uid, который начинает действовать, когда class пользователя отличается от wheel.

Если модуль дополняет другой модуль, элементы XML, добавляемые в представление, используют пространство имен дополняющего модуля. Например, если приведенный выше пример дополнения происходил в модуле с префиксом other, XML будет выглядеть, как показано ниже.

     <user>
       <name>alicew</name>
       <full-name>Alice N. Wonderland</full-name>
       <class>drop-out</class>
       <other:uid>1024</other:uid>
     </user>

Оператор augment описан в параграфе 7.17.

4.2.9. Определения операций

Язык YANG позволяет определять операции. Имена операций, а также входные и выходные параметры моделируются с использованием операторов определения данных YANG. Операции на верхнем уровне модуля определяются с помощью оператора rpc. Операции могут также привязываться к узлам данных типа container и list. Такие операции определяются с помощью оператора action.

Ниже приведен пример определения операции YANG верхнего уровня.

     rpc activate-software-image {
       input {
         leaf image-name {
           type string;
         }
       }
       output {
         leaf status {
           type string;
         }
       }
     }

Пример NETCONF XML

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <activate-software-image xmlns="http://example.com/system">
         <image-name>example-fw-2.3</image-name>
       </activate-software-image>
     </rpc>

     <rpc-reply message-id="101"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <status xmlns="http://example.com/system">
         The image example-fw-2.3 is being installed.
       </status>
     </rpc-reply>

Ниже представлен пример определения операции, привязанной к узлу данных типа list.

     list interface {
       key "name";

       leaf name {
         type string;
       }

       action ping {
         input {
           leaf destination {
             type inet:ip-address;
           }
         }
         output {
           leaf packet-loss {
             type uint8;
           }
         }
       }
     }

Пример NETCONF XML

     <rpc message-id="102"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <action xmlns="urn:ietf:params:xml:ns:yang:1">
         <interface xmlns="http://example.com/system">
           <name>eth1</name>
           <ping>
             <destination>192.0.2.1</destination>
           </ping>
         </interface>
       </action>
     </rpc>

     <rpc-reply message-id="102"
                xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
                xmlns:sys="http://example.com/system">
       <sys:packet-loss>60</sys:packet-loss>
     </rpc-reply>

Оператор rpc описан в параграфе 7.14, action – в параграфе 7.15.

4.2.10. Определения уведомлений

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

Пример YANG

     notification link-failure {
       description
         "A link failure has been detected.";
       leaf if-name {
         type leafref {
           path "/interface/name";
         }
       }
       leaf if-admin-status {
         type admin-status;
       }
       leaf if-oper-status {
         type oper-status;
       }
     }

Пример NETCONF XML

     <notification
         xmlns="urn:ietf:params:netconf:capability:notification:1.0">
       <eventTime>2007-09-01T10:00:00Z</eventTime>
       <link-failure xmlns="urn:example:system">
         <if-name>so-1/2/3.0</if-name>
         <if-admin-status>up</if-admin-status>
         <if-oper-status>down</if-oper-status>
       </link-failure>
     </notification>

Оператор notification описан в параграфе 7.16.

5. Концепции языка

5.1. Модули и субмодули

Модуль является базовым блоком определений в YANG. Модуль определяет одну модель данных. Модуль может также дополнять существующую модель новыми узлами.

Субмодулями называются частичные модули, вносящие вклад в определения модуля в целом. Модуль может включать произвольное число субмодулей, но каждый субмодуль может относиться лишь к одному модулю.

Разработчикам модулей и субмодулей YANG рекомендуется выбирать имена для своих модулей с учетом возможных конфликтов со стандартными или другими фирменными (enterprise) модулями, например, используя название организации в качестве префикса имени модуля. В рамках сервера все модули должны иметь уникальные имена.

Модули используют оператор include для перечисления всех своих субмодулей. Модуль или относящиеся к нему субмодули могут ссылаться на определения этого модуля и всех включенных в него субмодулей.

Модули и субмодули используют оператор import для ссылок на внешние модули. Операторы в модуле и субмодулях могут указывать определения из внешних модулей, используя префикс, указанный в операторе import.

Для совместимости с YANG версии 1 субмодуль может использовать оператор include для ссылки на другие субмодули того же модуля, но это не требуется в YANG версии 1.1. Субмодуль может ссылаться на любое определение в содержащем его модуле и всех его субмодулях. В субмодули недопустимо включать выпуски (revision) других субмодулей, отличающиеся от включенных в модуль.

В модули и субмодули недопустмимо включать субмодули из других модулей, а субмодулям недопустмиимо импортировать всключающии их (свой) модуль.

Операторы import и include служат для обеспечения доступности определений из других модулей:

  • для того, чтобы модуль или субмодуль мог ссылаться на определения из внешнего модуля, этот внешний модуль должен быть импортирован (import).

  • модуль должен включать (include) все свои субмодули;

  • модуль и его субмодули могут ссылаться на определения вэтого модуля и всех включенных в него субмодулей.

Недопустимо создавать замкнутые цепочки импорта. Например, если модуль a импортирует модуль b, то b не может импортировать a.

При ссылке на определение из внешнего модуля должен применяться локально заданный префикс, за которым следует разделитель в форме двоеточия (:) и внешний идентификатор. Ссылки на определения в локальном модуле также могут использовать префиксы. Поскольку встроенные типы данных не относятся к какому-либо модулю и не имеют префикса, для ссылок на встроенные типы данных (например, int32) префиксы применяться не могут. Синтаксис ссылок на определения формально задан правилом identifier-ref в разделе 14.

5.1.1. Импорт и включение по номеру выпуска (Revision)

Опубликованные модули могут независимо изменяться время от времени. Для обеспечения возможности совершенствования модули могут импортироваться с указанием конкретного выпуска (revision). Изначально в модули импортируются выпуски других модулей, которые существовали на момент разработки данного модуля. По мере публикации новых выпусков импортируемых модулей импортирующий модуль не будет автоматически меняться. Если автор модуля готов перейти к более новому выпуску импортируемого модуля, он публикует свой модуль заново с обновлением операторов import. Таким образом авторы модулей явно указывают совместимость с новым выпуском импортируемого модуля.

Для субмодулей ситуация похожа, но проще. Модуль или субмодуль, включающий другие субмодули, может указать выпуск (revision) включаемых субмодулей. Если субмодуль изменяется, все включающие его модули и субмодули нужно будет изменить, указав ссылку на новый выпуск.

Например, модуль b импортирует модуль a.

     module a {
       yang-version 1.1;
       namespace "urn:example:a";
       prefix "a";

       revision 2008-01-01 { ... }
       grouping a {
         leaf eh { .... }
       }
     }

     module b {
       yang-version 1.1;
       namespace "urn:example:b";
       prefix "b";

       import a {
         prefix "p";
         revision-date 2008-01-01;
       }

       container bee {
         uses p:a;
       }
     }

Когда автор модуля a публикует новый выпуск, изменения могут оказаться не приемлемыми с точки зрения автора модуля b. Если же новый выпуск пригоден для импорта, автор модуля b публикует свой модуль заново с обновленным оператором import.

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

5.1.2. Иерархии модулей

YANG позволяет моделировать данные с множеством иерархий, когда данные могут иметь более одного узла верхнего уровня. Каждый узел верхнего уровня в модели определяет отдельную иерархию. Модели с множеством узлов верхнего уровня иногда очень удобны и поддерживаютя YANG.

5.1.2.1. Представление NETCONF XML

Протокол NETCONF способен передавать любые данные XML в качестве содержимого элементов <config> и <data>. Узлы верхнего уровня модулей YANG представляются внутри этих элементов в произвольном порядке, как дочерние элементы. Такая инкапсуляция гарантирует, что соответствующие сообщения NETCONF всегда будут корректно сформированными документами XML.

Например, экземпляр

     module example-config {
       yang-version 1.1;
       namespace "urn:example:config";
       prefix "co";

       container system { ... }
       container routing { ... }
     }

может быть представлен в NETCONF в форме

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
          xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <system xmlns="urn:example:config">
             <!-- системные данные -->
           </system>
           <routing xmlns="urn:example:config">
             <!-- данные маршрутизации -->
           </routing>
         </config>
       </edit-config>
     </rpc>

5.2. Макет файла

Модули и субмодули YANG обычно сохраняются в файлах с одним оператором module или submodule в каждом файле. Для имен файлов следует использовать приведенную ниже форму.

     module-or-submodule-name ['@' revision-date] ( '.yang' / '.yin' )

Компонента module-or-submodule-name указывает имя модуля или субмодуля, необязательная компонента revision-date указывает последний выпуск модуля или субмодуля, указанный оператором revision (параграф 7.1.9).

Расширение имени .yang говорит о том, что содержимое этого файла использует синтаксис YANG (раздел 6), а .yin указывает использование синтаксиса YIN (раздел 13).

Анализаторы YANG могут находить импортируемые модули и включаемые субмодули на базе этих соглашений.

5.3. Пространства имен XML

Все определения YANG задаются внутри модуля. Каждый модуль привязан к определенному пространству имен XML [XML-NAMES], которое является уникальным в глобальном масштабе идентификатором URI [RFC3986]. Клиент и сервер NETCONF используют пространство имен при кодировании данных XML.

Пространства имен XML для модулей, опубликованные в серии RFC [RFC4844], должны выделяться агентством IANA (см раздел 14 в [RFC6020]).

Пространства имен XML для прочих (фирменных) модулей должны выделяться организацией, владеющей модулем, без централизованной регистрации. Идентификаторы URI для пространств имен должны выбираться так, чтобы не возникало конфликтов со стандартными или другими фирменными пространствами имен. Например, они могут включать имя компании или организации.

Оператор namespace описан в параграфе 7.1.3.

5.3.1. Пространство имен YANG XML

YANG определяет пространство имен XML для операций NETCONF <edit-config>, содержимого <error-info> и элемента <action>. Это пространство имеет имя urn:ietf:params:xml:ns:yang:1.

5.4. Преобразование имен группировок, типов и отождествлений

Имена группировок (grouping), типов (type) и отождествлений (identity) преобразуются в контексте их определения, а не в контексте применения. Пользователи grouping, typedef и identity не обязаны импортировать модули или включать субмодули для удовлетворения всех требований, заданных исходным определением. Это похоже на область действия (scope) в традиционных языках программирования.

Например, если модуль имеет группировку, в которой присутствует ссылка на тип, при использовании этой группировки во втором модуле тип преобразуется (resolve) в контексте исходного (а не второго) модуля. За счет этого не возникает неоднозначностей при определении типа в обоих модулях.

5.5. Вложенные определения типов и группировки

Определения типов (typedef) и группипровки (grouping) во многих операторах YANG могут быть вложенными, что позволяет лексически охватывать их иерархией операторов, в которой они появляются. Это дает возможность определять типы и группировки вблизи места их применения, а не на вершине иерархии. Такая близость улучшает читаемость определений.

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

Наконец, обозначение области действия позволяет автору модуля сохранить типы и группировки (приватными) внутри модуля или субмодуля и предотвратить их повторное использование (reuse). Поскольку за пределами модуля или субмодуля могут применяться лишь типы и группировки верхнего уровня (т. е. те, которые указаны в субоператорах операторов module или submodule), разработчик получает больше контроля над компонентами своих модулей, представленными во внешний мир, может скрыть внутреннюю структуру и установить границу между видимыми извне и приватными частями.

Определениям области действия недопустимо затенять определения с более широкой областью действия. Тип и группировка не могут быть определены, если более высокий уровень в иерархии операторов уже включает определение с таким идентификатором.

Ссылка на тип или группировку без префикса или с префиксом текущего модуля преобразуется (resolve) путем нахождения соответствующего оператора typedef или grouping среди непосредственных субоператоров каждого оператора предка.

5.6. Соответствие

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

Для YANG возможны три варианта соответствия:

  • базовое поведение модели;

  • необязательные функции в составе модели;

  • отклонения от модели.

Эти варианты более подробно рассматриваются ниже.

5.6.1. Базовое поведение

Модель определяет соглашение между клиентом и сервером на базе YANG — это соглашение позволяет обеим сторонам верить в то, что другая сторона знает синтаксис и семантику моделируемых данных. Сила YANG заключается в выполнении этого соглашения.

5.6.2. Необязательные функции

Во многих моделях авторы делают некоторые части модели не обязательными (условными). Сервер самостоятельно определяет какие из этих частей пригодны и поддерживаются им.

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

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

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

Возможности определяются с помощью оператора feature. Определения в модуле, которые являются условными по отношению к этой функции, помечаются оператором if-feature.

Дополнительная информация о необязательных функциях (возможностях) приведена в параграфе 7.20.1.

5.6.3. Отклонения от модели

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

Например, модуль BGP может поддерживать любое число партнеров BGP, а конкретный сервер ограничивается поддержкой 16 партнеров. Любое приложение, пытающееся настроить семнадцатого партнера, столкнется с ошибкой. Хотя этой ошибки приложению может оказаться достаточно для того, чтобы понять ограничение, лучше было бы приложению заранее знать об этом и принять соответствующие меры.

Отклонения серверов от модели могут объявляться с использованием оператора deviation, который принимает в качестве аргумента строку с идентификатором узла в дереве схемы. Содержимое этого оператора уточняет информацию об отклонении сервера от заданного в модуле поведения.

Описание оператора deviation приведено в параграфе 7.20.3.

5.6.4. Анонсирование информации о соответствии в NETCONF

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

Сервер NETCONF должен анонсировать реализуемые им модули (см. параграф5.6.5) путем реализации модуля YANG ietf-yang-library, определенного в [RFC7895] и перечисления всех реализованных на сервере моделей в списке /modules-state/module.

Сервер также должен анонсировать в сообщении <hello> приведенную ниже возможность.

urn:ietf:params:netconf:capability:yang-library:1.0?revision=<date>&module-set-id=<id>

Параметр revision имеет такое же значение, как дата выпуска модуля ietf-yang-library, реализованного сервером. Этот параметр должен присутствовать.

Параметр module-set-id имеет такое же значение, как лист /modules-state/module-set-idиз модуля ietf-yang-library. Этот параметр должен присутствовать.

С помощью этого механизма клиент может кэшировать поддерживаемые сервером модули и обновлять кэш лишь при изменении значения module-set-id в сообщении <hello>.

5.6.5. Реализация модуля

Сервер реализует модуль, если в нем реализованы узлы данных, RPC, действия (actions), уведомления и отклонения (deviations) для этого модуля.

Серверам недопустимо реализовать одновременно более одного выпуска модуля.

Если сервер реализует модуль A, который импортирует модуль B, и а A применяет любой из узлов модуля B в операторе augment или path, который поддерживает сервер, этот сервер должен реализовать выпуск модуля B, в котором эти узлы определены. Это не зависит от того, импортирован модуль B по выпуску или нет.

Если сервер реализует модуль A, который импортирует модуль C без указания даты выпуска модуля C, и сервер не реализует C (например, если C содержит лишь операторы typedef), сервер должен указать модуль C в списке /modules-state/module из ietf-yang-library [RFC7895] и должен установить лист conformance-type на import для этого модуля.

Если сервер указывает модуль C в списке /modules-state/module из ietf-yang-library и имеются другие модули M, которые импортируют C без указания выпуска модуля wC, сервер должен использовать определения из последней версии модуля C, указанной для модулей M.

Эти правила обусловлены тем, что клиенты должны иметь возможность узнать конкретную структуру и типы всех листьев и листьев-списков модели данных, реализованные на сервере.

Рассмотрим в качестве примера приведенные ниже модули.

     module a {
       yang-version 1.1;
       namespace "urn:example:a";
       prefix "a";

       import b {
         revision-date 2015-01-01;
       }
       import c;

       revision 2015-01-01;

       feature foo;

       augment "/b:x" {
         if-feature foo;

         leaf y {
           type b:myenum;
         }
       }

       container a {
         leaf x {
           type c:bar;
         }
       }
     }

     module b {
       yang-version 1.1;
       namespace "urn:example:b";
       prefix "b";

       revision 2015-01-01;

       typedef myenum {
         type enumeration {
           enum zero;
         }
       }

       container x {
       }
     }

     module b {
       yang-version 1.1;
       namespace "urn:example:b";
       prefix "b";

       revision 2015-04-04;
       revision 2015-01-01;

       typedef myenum {
         type enumeration {
           enum zero; // добавлено 2015-01-01
           enum one;  // добавлено 2015-04-04
         }
       }

       container x {  // добавлено 2015-01-01
         container y; // добавлено 2015-04-04
       }
     }

     module c {
       yang-version 1.1;
       namespace "urn:example:c";
       prefix "c";

       revision 2015-02-02;

       typedef bar {
         ...
       }
     }

     module c {
       yang-version 1.1;
       namespace "urn:example:c";
       prefix "c";

       revision 2015-03-03;
       revision 2015-02-02;

       typedef bar {
         ...
       }
     }

Сервер, который реализует выпуск 2015-01-01 модуля a и поддерживает функцию foo, может реализовать выпуск 2015-01-01 или 2015-04-04 для модуля b. Поскольку модуль b был импортирован выпуском, тип листа /b:x/a:y не меняется в зависимости от используемого сервером выпуска модуля b.

Сервер, который реализует модуль a, но не поддерживает функцию foo, не будет реализовать модуль b.

Сервер, реализующий выпуск 2015-01-01 модуля a, указывают любой выпуск модуля c и перечисляет его в списке /modules-state/module из ietf-yang-library.

Приведенный ниже пример кода XML показывает пригодные данные для списка /modules-state/module сервера, который реализует модуль a.

     <modules-state
         xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
       <module-set-id>ee1ecb017370cafd</module-set-id>
       <module>
         <name>a</name>
         <revision>2015-01-01</revision>
         <namespace>urn:example:a</namespace>
         <feature>foo</feature>
         <conformance-type>implement</conformance-type>
       </module>
       <module>
         <name>b</name>
         <revision>2015-04-04</revision>
         <namespace>urn:example:b</namespace>
         <conformance-type>implement</conformance-type>
       </module>

       <module>
         <name>c</name>
         <revision>2015-02-02</revision>
         <namespace>urn:example:c</namespace>
         <conformance-type>import</conformance-type>
       </module>
     </modules-state>

5.7. Модификация хранилища данных

Модели данных могут разрешать серверу менять хранилище конфигурации способами, которые не заданы явно в сообщениях протокола сетевого управления. Например, модель данных может определять листья, которым присваиваются определенные системой значения, если клиент их не предоставил. Формальный механизм задания обстоятельств, при которых такие изменения разрешены, выходит за рамки этой спецификации.

1Constrained Application Protocol (CoAP) Management Interface — интерфейс управления протоколом ограниченных приложений.

2Extensible Markup Language.

3XML Path Language.

4YANG Independent Notation — независимая от YANG нотация.

5Extensible Stylesheet Language Transformation — преобразование расширяемого языка стилей.

6Structure of Management Information — структура данных управления.

7Simple Network Management Protocol — простой протокол управления сетями.

 

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

Добавить комментарий

Or