Internet Engineering Task Force (IETF) M. Bjorklund Request for Comments: 8340 Tail-f Systems BCP: 215 L. Berger, Ed. Category: Best Current Practice LabN Consulting, L.L.C. ISSN: 2070-1721 March 2018
Диаграммы деревьев YANG
YANG Tree Diagrams
Аннотация
В этом документе описан современный синтаксис, применяемый в диаграммах деревьев модулей YANG. Цель документа заключается в сборе всех определений в одном месте. Синтаксис может время от времени обновляться по мере развития языка YANG.
Статус документа
Этот документ относится к категории обмена опытом (Internet Best Current Practice).
Документ является результатом работы IETF1 и представляет согласованное мнение сообщества IETF. Документ был представлен на публичное рассмотрение и был одобрен для публикации IESG2. Дополнительную информацию о документах серии BCP можно найти в разделе 2 RFC 7841.
Информацию о текущем статусе документа, замеченных ошибках и способах обратной связи можно получить по ссылке https://www.rfc-editor.org/info/rfc8340.
Авторские права
Авторские права (Copyright (c) 2018) принадлежат 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 впервые были опубликованы в RFC 6536. Они используются для упрощённого графического представления модели данных и могут создаваться автоматически с помощью таких инструментов, как pyang [PYANG]. В этом документе описан синтаксис, применяемый в диаграммах деревьев YANG. Предполагается, что этот документ будет обновляться или заменяться по мере внесения изменений в язык YANG [RFC7950].
Сегодня определения синтаксиса, использованного для представления модуля YANG, зачастую включаются в каждый документ с диаграммами деревьев. Такой подход связан с рядом недостатков, поэтому целью данного документа является создание единой точки, где представлены такие определения. Документ не предназначен для ограничения будущих изменений и служит скорей для того, чтобы такие изменения были согласованными и легко идентифицируемыми.
Пример диаграммы дерева можно найти в разделе 3 документа [RFC8343]. Часть такого дерева приведена ниже.
+--rw interfaces
+--rw interface* [name]
+--rw name string
+--rw description? string
+--rw type identityref
+--rw enabled? boolean
+--rw link-up-down-trap-enable? enumeration {if-mib}?
2. Синтаксис диаграммы дерева
В этом разделе описано значение символов, применяемых в диаграммах деревьев YANG.
Полная диаграмма дерева модуля представляет все элементы и включает имя модуля и разделы для операторов верхнего уровня (обычно контейнеры), дополнений, rpc и уведомлений, идентифицируемых оператором module. Деревья модулей могут включаться в документ целиком, одной или несколькими частями и даже подмножеством узлов.
Модуль указывается тегом module:, за которым следует имя модуля <module-name>. Далее следует один или несколько разделов в соответствии с приведёнными ниже правилами.
-
Определённые в модуле узлы верхнего уровня смещаются пробелами на две позиции.
-
Добавления смещаются на две пробельных позиции и указываются ключевым словом augment, за которым следует целевой узел и двоеточие (:).
-
RPC смещаются на два пробела и указываются тегом rpcs:.
-
Уведомления смещаются на два пробела и указываются тегом notifications:.
-
Группировки смещаются на два пробела и указываются ключевым словом grouping, за которым следует имя группировки и двоеточие (:).
-
Структуры yang-data смещаются на два пробела и указываются ключевым словом yang-data, за которым следует имя структуры yang-data и двоеточие (:).
Относительная организация каждого раздела обеспечивается с использованием текстового формата, который обычно применяется для вывода команд отображения дерева каталогов файловых систем. Каждый узел дерева имеет префикс +–. Узлы схемы, являющиеся потомками другого узла смещаются от родителя на три пробела. Братские узлы схемы указываются с одинаковым смещением и разделяются пустой строкой, а для связывания служит символ |.
Пример полного формата с учётом соглашений о смещениях приведён ниже.
module: <module-name>
+--<node>
| +--<node>
| +--<node>
+--<node>
+--<node>
+--<node>
augment <target-node>:
+--<node>
+--<node>
+--<node>
+--<node>
augment <target-node>:
+--<node>
rpcs:
+--<rpc-node>
+--<rpc-node>
+--<node>
| +--<node>
+--<node>
notifications:
+--<notification-node>
+--<notification-node>
+--<node>
| +--<node>
+--<node>
grouping <grouping-name>:
+--<node>
+--<node>
| +--<node>
+--<node>
grouping <grouping-name>:
+--<node>
yang-data <yang-data-name>:
+--<node>
+--<node>
| +--<node>
+--<node>
yang-data <yang-data-name>:
+--<node>
2.1. Субмодуль
Субмодули представляются аналогично модулям, но указываются тегом submodule:, за которым следует имя субмодуля <module-name>. Например,
submodule: <module-name>
+--<node>
| +--<node>
| +--<node>
2.2. Группировка
Узлы в используемой группировке обычно раскрываются, как будто они определены в месте расположения оператора uses. Однако можно не раскрывать оператор uses, а вместо этого просто указывать имя группировки.
Например, приведённая ниже диаграмма показывает группировку tls-transport из [RFC7407] без раскрытия
+--rw tls
+---u tls-transport
Если группу раскрыть, она пример вид
+--rw tls
+--rw port? inet:port-number
+--rw client-fingerprint? x509c2n:tls-fingerprint
+--rw server-fingerprint? x509c2n:tls-fingerprint
+--rw server-identity? snmp:admin-string
Группировки могут присутствовать в разделе groupings.
2.3. Структура yang-data
Если модуль определяет структуры yang-data [RFC8040], эти структуры могут присутствовать в разделе yang-data.
2.4. Сжатое представление узлов
Когда состав узлов внутри схемы модуля не имеет значения в контексте представления дерева, братские узлы и их потомки могут быть «сжаты» с использованием трёх точек (…) вместо строк, представляющих реальные узлы.
+--<node>
| ...
+--<node>
+--<node>
+--<node>
2.5. Комментарий
Отдельная строка комментария, начинающегося с символов // (возможно смещённых) и длящегося до конца строки, может использоваться в дереве.
2.6. Представление узла
Каждый узел модуля YANG указывается в форме
<status>--<flags> <name><opts> <type> <if-features>
<status>
+ текущий
x устаревший (deprecated)
o отменённый (obsolete)
<flags>
rw для узлов данных конфигурации и узлов выбора
ro для узлов неконфигурационных данных и узлов выбора,
выходных параметров rpc и операций (actions), а
также параметров уведомлений
-w для входных параметров rpc и операций
-u для использования в группировках
-x для rpc и операций
-n для уведомлений
mp для узлов с оператором расширения mount-point
Узлы вариантов (case) не имеют флагов.
<name> имя узла
(<name>) означает, что узел задаёт выбор (choice)
:(<name>) означает, что узел задаёт вариант (case)
Если узел добавлен в дерево из другого модуля, его имя указывается в форме <prefix>:<name>, где <prefix> указывает префикс, заданный в модуле, где определён узел.
Если узел является вариантом (case) перед <name> пробелы не используются.
<opts>
? для опционального узла leaf, choice, anydata, anyxml
! для контейнера присутствия
* для leaf-list или list
[<keys>] для ключей списка
/ для узла данных верхнего уровня в смонтированном модуле
@ для узла данных верхнего уровня модуля, указанного в точке
монтирования родительской ссылки
<type> название типа для leaf и leaf-list
Для leafref тип указывается как (1) -> TARGET, где TARGET указывает путь leafref с удалением (по возможности) ссылок или (2) leafref.
<if-features> список функций (feature) от которых узел зависит,
указывается в фигурных скобках, за которыми следует символ ? {...}?
Между разделяемыми пробелами полями (например, <opts> и <type>) число пробелов может быть любым. Дополнительные пробелы могут применяться для выравнивания полей (например, в списке или контейнере) с целью удобочитаемости.
3. Рекомендации по использованию в RFC
В этом разделе приводятся рекомендации, связанные с использованием диаграмм деревьев в RFC.
3.1. Разрыв длинных строк
В документах Internet-Draft и RFC размер строки ограничен 72 символами. Когда представление узла требует более длинной строки, следует использовать перевод строки между <opts> и <type> или между <type> и <if-feature>. Новую строку следует дополнить пробельными символами так, чтобы она начиналась под <name> со смещением в 2 символа.
notifications:
+---n yang-library-change
+--ro module-set-id
-> /modules-state/module-set-id
Длинные пути (например, пути leafref или цели дополнения) можно разбивать на несколько строк. Например,
augment /nat:nat/nat:instances/nat:instance/nat:mapping-table
/nat:mapping-entry:
Упомянутая выше команда pyang помогает в создании нужного форматирования. Например, приведённая выше диаграмма уведомлений создана с помощью команды
pyang -f tree --tree-line-length 50 ietf-yang-library.yang
При включении диаграмм в качестве рисунков в Internet-Draft или RFC имеет смысл указать –tree-line-length 69.
3.2. Группировки
Если модуль YANG состоит только из группировок, диаграмма дерева должна включать группировки. Можно снова воспользоваться компилятором pyang для создания диаграммы дерева с группировками, используя параметры -f tree –tree-print-groupings.
3.3. Длинные диаграммы
Диаграммы можно разбивать на несколько разделов в соответствии со структурой документа. Поскольку диаграммы предназначены для упрощённого представления модулей, обычно следует избегать диаграмм, выходящих за пределы одной страницы. Если полная диаграмма для модуля слишком длинна, её можно разбить на несколько более мелких диаграмм. Например, можно представить диаграмму с данными узла и другую диаграмму со всеми уведомлениями. Если дерево узлов получается слишком длинным, его можно разбить на несколько диаграмм для отдельных ветвей. При включении диаграмм в документ авторам следует решить, включать длинную диаграмму в основной документ или в приложение в нему.
Пример разделения диаграммы можно видеть в [RFC7407], где параграф 2.4 включает диаграмму конфигурации engine
+--rw snmp
+--rw engine
// дополнительные параметры из ветви engine
Далее в параграфе 2.5 [RFC7407] показана диаграмма конфигурации target
+--rw snmp
+--rw target* [name]
// дополнительные параметры из ветви target
Уже упомянутая команда pyang будет полезна для создания таких деревьев. Для приведённого выше примера использовалась команда
pyang -f tree --tree-path /snmp/target ietf-snmp.yang
4. Диаграммы деревьев с точками монтирования YANG
Монтирование схемы YANG, определённое в [SCHEMA-MOUNT], требует некоторого обсуждения. Монтирование схемы является базовым механизмом, который позволяет монтировать один или несколько модулей YANG в заданном месте другой (родительской) схемы. Место установки указывается «точкой монтирования» и любой контейнер или список могут служить в качестве таких точек. Точки монтирования указываются путём включения оператора расширения mount-point в качестве субоператора для узла контейнера или списка. Таким образом узлы точек монтирования напрямую указываются в определении схемы модуля и могут быть указаны в дереве с помощью флага mp.
В следующем примере, заимствованном из [YANG-NIs], контейнер vrf-root включает оператор расширения mount-point в качестве части своего определения.
module: ietf-network-instance
+--rw network-instances
+--rw network-instance* [name]
+--rw name string
+--rw enabled? boolean
+--rw description? string
+--rw (ni-type)?
+--rw (root-type)
+--:(vrf-root)
| +--mp vrf-root
4.1. Представление деревьев с точками монтирования
Реальные модули, доступные под точкой монтирования, контролируются сервером и предоставляются клиентам. Эта информация обычно представляется через модуль монтирования схемы (ietf-yang-schema-mount), определённый в [SCHEMA-MOUNT]. Модуль монтирования схемы поддерживает раскрытие (exposure) как смонтированных схем, так и «родительских ссылок». Последние используются для оценки выражений XPath3 в смонтированных модулях и не представляют доступные клиенту пути, указанная ссылкой информация доступна клиентам через родительскую схему. Монтирование схемы также определяет «встроенный» (inline) тип точек монтирования, где смонтированные модули раскрываются через библиотечный модуль YANG.
Хотя доступные под точкой монтирования модули не указываются в модулях YANG с точками монтирования, определяющий модуль документ будет описывать предусмотренное использование модуля и может указывать как модули, которые будут монтироваться, так и родительские модули, на которые монтируемые модули могут ссылаться. Пример такого описания можно найти в [YANG-NIs]. Конкретная реализация модуля с точками монтирования будет также поддерживать список монтируемых и указанных ссылками модулей. В описании предполагаемого использования и фактической реализации полезно указать, как смонтированные модули будут создаваться и указываться под точкой монтирования в диаграмме дерева.
В таких диаграммах точку монтирования следует рассматривать аналогично контейнеру, использующему группировку. Флаги следует устанавливать с учётом листа config, упомянутого выше, а указанные выше опции монтирования должны быть показаны для узлов верхнего уровня в монтируемом или указанном ссылкой модуле. В следующем примере, взятом из [YANG-Nis], представлен предыдущий пример с установленными модулями YANG ietf-routing [YANG-Routing] и ietf-ospf [OSPF-YANG], узлами из модуля YANG ietf-interfaces [RFC8343], доступными через родительскую ссылку, и узел config со значением true.
module: ietf-network-instance
+--rw network-instances
+--rw network-instance* [name]
+--rw name string
+--rw enabled? boolean
+--rw description? string
+--rw (ni-type)?
+--rw (root-type)
+--:(vrf-root)
+--mp vrf-root
+--ro rt:routing-state/
| +--ro router-id?
| +--ro control-plane-protocols
| +--ro control-plane-protocol* [type name]
| +--ro ospf:ospf
| +--ro instance* [af]
| ...
+--rw rt:routing/
| +--rw router-id?
| +--rw control-plane-protocols
| +--rw control-plane-protocol* [type name]
| +--rw ospf:ospf
| +--rw instance* [af]
| ...
+--ro if:interfaces@
| ...
+--ro if:interfaces-state@
| ...
Следует подчеркнуть, что модуль ietf-ospf дополняет ietf-routing и хотя он не указан в модуле монтирования схемы (или встроенной библиотеке YANG), в диаграмме дерева не используется специального обозначения монтирования.
Определения точки монтирования, самого по себе, не достаточно для указания используются ли смонтированные модули для данных конфигурации или иных данных. Это определяется листом config модуля ietf-yang-schema-mount, связанным с конкретной точкой монтирования и указывается на смонтированных узлах верхнего уровня. Например, в приведённом выше дереве, где лист config для модуля ietf-routing указывает false, узлы в ветви rt:routing будут иметь другие флаги.
+--ro rt:routing/
| +--ro router-id?
| +--ro control-plane-protocols
...
5. Взаимодействие с IANA
Этот документ не требует действий IANA.
6. Вопросы безопасности
Описанные здесь диаграммы деревьев не оказывают влияния на безопасность.
7. Литература
[OSPF-YANG] Yeung, D., Qu, Y., Zhang, J., Chen, I., and A. Lindem, “Yang Data Model for OSPF Protocol”, Work in Progress4, draft-ietf-ospf-yang-10, March 2018.
[PYANG] “pyang”, February 2018, <https://github.com/mbj4668/pyang>.
[RFC7407] Bjorklund, M. and J. Schoenwaelder, “A YANG Data Model for SNMP Configuration”, RFC 7407, DOI 10.17487/RFC7407, December 2014, <https://www.rfc-editor.org/info/rfc7407>.
[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>.
[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>.
[SCHEMA-MOUNT] Bjorklund, M. and L. Lhotka, “YANG Schema Mount”, Work in Progress5, draft-ietf-netmod-schema-mount-08, October 2017.
[YANG-NIs] Berger, L., Hopps, C., Lindem, A., Bogdanovic, D., and X. Liu, “YANG Model for Network Instances”, Work in Progress6, draft-ietf-rtgwg-ni-model-11, March 2018.
[YANG-Routing] Lhotka, L., Lindem, A., and Y. Qu, “A YANG Data Model for Routing Management (NMDA Version)”, Work in Progress7, draft-ietf-netmod-rfc8022bis-11, January 2018.
Адреса авторов
Martin Bjorklund
Tail-f Systems
Email: mbj@tail-f.com
Lou Berger (редактор)
LabN Consulting, L.L.C.
Email: lberger@labn.net
Перевод на русский язык
Николай Малых
1Internet Engineering Task Force – комиссия по решению инженерных задач Internet.
2Internet Engineering Steering Group – комиссия по инженерным разработкам Internet.
3XML Path Language – язык путей XML.