Internet Engineering Task Force (IETF) M. Veillette, Ed.
Request for Comments: 9595 Trilliant Networks Inc.
Category: Standards Track A. Pelov, Ed.
ISSN: 2070-1721 IMT Atlantique
I. Petrov, Ed.
Google Switzerland GmbH
C. Bormann
Universität Bremen TZI
M. Richardson
Sandelman Software Works
July 2024
YANG Schema Item iDentifier (YANG SID)
Идентификатор элемента схемы YANG
Аннотация
Идентификатор элемента схемы YANG (YANG Schema Item iDentifier или YANG SID) – глобально уникальное 63-битовое целое число без знака, служащее для идентификации элементов YANG. SID обеспечивают более компактный метод идентификации тех элементов YANG, которые могут использоваться эффективно, в частности, в средах с ограничениями (RFC 7228). Этот документ задаёт семантику, процессы регистрации и процессы назначения YANG SID для управляемых IETF модулей YANG. Для обеспечения возможности реализации процессов документ также определяет формат файла, используемый для хранения и публикации назначенных YANG SID.
Статус документа
Документ относится к категории Internet Standards Track.
Документ является результатом работы IETF1 и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG2. Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 7841.
Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc9595.
Авторские права
Авторские права (Copyright (c) 2024) принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.
К документу применимы права и ограничения, перечисленные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно, поскольку в них описаны права и ограничения, относящиеся к данному документу. Компоненты кода, извлечённые из этого документа, должны включать текст пересмотренной лицензии BSD (Revised BSD License), как указано в параграфе 4.e документа Trust Legal Provisions и предоставляются без гарантий, как указано в Revised BSD License.
1. Введение
Для некоторых элементов, определённых в YANG [RFC7950], требуется использовать уникальный идентификатор. В протоколах NETCONF3 [RFC6241] и RESTCONF [RFC8040] эти идентификаторы реализуются в форме имён. Для реализации моделей данных YANG в устройствах [RFC7228] и сетях с ограничениями, требуется более компактный метод идентификации элементов YANG. Этот компактный идентификатор, называемый идентификатором элемента схемы YANG (YANG Schema Item iDentifier, YANG SID или просто SID, когда контекст в этом документе понятен), представляется в форме 63-битового целого числа без знака. Ограничение размера 63 битами позволяет проще работать с SID на платформах, где для иных задач не требуется поддержка операций с 64-битовыми целыми числами без знака. Потеря одного бита не является существенной с учётом остающегося пространства значений.
С использованием SID указываются:
-
отождествления (идентификаторы);
-
узлы данных (включая узлы, заданные расширениями rc:yang-data [RFC8040] и sx:structure [RFC8791]);
-
вызовы удалённых процедур (remote procedure call, RPC) и связанные с ними входные и выходные данные);
-
действия и связанные с ними входные и выходные данные);
-
уведомления и связанная с ними информация;
-
модули YANG и свойства (функции).
Возможно, что некоторые протоколы будут использовать лишь часть назначенных SID. Например, для отличных от NETCONF [RFC6241] протоколов, предоставляющих доступ к данным на основе моделей YANG, таких как [CORE-COMI], доставка SID модуля YANG может быть ненужной. Доставка такой информации может потребоваться другим протоколам, например, протоколам, связанным с обнаружением, таким как библиотека модулей YANG с ограничениями (Constrained YANG Module Library) [YANG-LIBRARY].
SID – это глобально уникальные целые числа. Для обеспечения уникальности применяется система регистрации. SID регистрируются блоками (диапазонами) – SID range. После признания SID «стабильными» они назначаются навсегда. Элементы, назначенные новой версией модуля YANG добавляются в список уже выделенных SID. Этот вопрос более подробно рассматривается в разделе 2.
Присвоение SID элементам YANG обычно выполняется автоматизировано, как описано в Приложении B, где рассмотрены также случаи, когда может быть уместно ручное вмешательство.
В разделе 3 подробно рассматриваются процессы регистрации для модулей YANG и связанных с ними SID. Для обеспечения реализации этих процессов в разделе 4 определён стандартный формат файлов для хранения и публикации SID.
Управляемые IETF модули YANG, которым нужно выделить SID, будут использовать механизмы IANA, заданные в этом документе (см. раздел 6). Для модулей YANG других организаций выделение SID происходит с помощью механизмов IANA через мегадиапазоны (Mega-Range, см. параграф 6.3), в рамках которых соответствующая сторона может использовать свои механизмы выделения значений.
YANG SID особенно полезны для компактного кодирования YANG-CBOR [RFC9254]. На момент создания этого документа инструмент для автоматизированного создания файлов .sid был доступен в рамках проекта с открытым кодом PYANG [PYANG].
1.1. Термины и обозначения
Ключевые слова необходимо (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.
Ниже перечислены элементы, определённые в [RFC7950].
- action
- feature
- module
- notification
- RPC
- schema node
- schema tree
- submodule
В этой спецификации также используются указанные ниже термины.
Item – элемент
Узел схемы, идентификатор (отождествление), модуль или свойство, заданные с использованием языка моделирования YANG.YANG Schema Item iDentifier (YANG SID или SID) – идентификатор узла схемы YANG
Целое число без знака, служащее для идентификации элемента YANG (см. параграф 3.2 в [RFC9254]).YANG name – имя YANG
Текстовая строка, служащая для идентификации элемента YANG (см. параграф 3.3 в [RFC9254]).2. Цели
Главная цель системы назначения и регистрации SID состоит в обеспечении глобальной совместимости протоколов, применяющих SID для обмена данными, смоделированными в YANG. Это вносит определённые требования к стабильности SID, но не препятствует активному развитию модулей YANG, для поддержки которых предназначены SID. Дополнительные цели включают:
-
предоставление разработчикам модулей YANG возможности создания относящихся к этим модулям SID;
-
упрощение разработчикам YANG получения SID;
-
предоставление другим разработчикам возможности задания SID для модулей, создатели которых не заинтересовались назначением SID;
-
поддержка режима назначения, при котором короткие SID (2-4 байта) легко доступны для приложений, где они будут полезны, в сочетании с использованием 63-битового пространства SID для облегчения действий, не требующих разрешения;
-
предоставление множеству организаций возможности предлагать услуги в поддержку назначения SID;
-
поддержка некоторой лакальности назначения SID для эффективного использования диапазонов (SID delta);
-
предоставление различным программным компонентам возможности работать с SID без полной информации о других участниках коммуникационных процессов.
Хотя реестры, управляющие SID для определяемых IETF модулей, в конечном итоге поддерживает IANA, нужны различные инструменты (такие как каталог YANG [yangcatalog]) для предоставления возможности назначать и использовать SID в модулях, ещё находящихся в разработке IETF. Разработчикам открытых и фирменных модулей YANG требуется возможность автономного назначения идентификаторов, возможно, с формированием независимых от IETF объединений, с сохранением общего пространства значений SID, управляемого IANA. Очевидно, что этот процесс имеет много сходства с распределением адресов IP, но между ними есть и существенные различия.
2.1. Технические цели
Как отмечено в введении, идентификаторы SID задуманы как глобально уникальные целые числа без знака. Это, в частности, означает цель 1 (MUST – должно):
Любое 63-битовое целое число без знака (1) либо не назначается как SID, либо (2) незыблемо связывается в точности с одним именем YANG. Разрешен лишь переход невыделенных значений в число привязанных навсегда.Это позволяет получателю структуры данных, содержащей SID, преобразовать их в глобально значимые имена YANG, которые применяются в настоящее время в имеющихся кодировках данных YANG, таких как YANG-XML [RFC7950] и YANG-JSON [RFC7951].
Термин «имя YANG» не определён вне этого документа и в YANG применяется сложная схема имён и сущностей, которые могут иметь имена. Вместо технического определения термина набор целей использует его так, чтобы были достигнуты общие цели YANG SID. Желательная цель 2 (SHOULD – следует):
Любое активно применяемое имя YANG имеет один назначенный ему идентификатор SID.Это означает, что:
-
не следует иметь имена YANG без назначенного SID;
-
именам YANG не следует иметь несколько SID.
Эти цели в полной мере не достижимы, поскольку имена YANG не обязательно создаются с назначением SID, а совершенно не связанные органы (сущности) могут назначить SID для одного имени YANG, не взаимодействуя между собой (как корабли в ночи). Отметим, что при сохранении такой автономности у любого отдельного наблюдателя будет складываться впечатление, что цель 2 достигнута. Отклонение будет замечено лишь при общении автономно действовавших сущностей.
2.2. Эволюция и версии модулей
Модули YANG эволючионируют (см. раздел 11 в [RFC7950] и параграф 4.27 в RFC 8407 [BCP216]), а технические цели с формулированы выше без учёта этого развития. Однако некоторые модули все ещё находятся в очень подвижном состоянии и назначать постоянные SID именам YANG из таких модулей нежелательно. Это относится не только к новым модулям, но и к создаваемым новым версиях имеющихся стабильных модулей. С этим связана цель 3 (MUST – должно):
Система назначения SID независима от версий модулей.
2.3. Компоненты решения и производные цели
Для гарантии уникальности SID применяется система регистрации. Чтобы обеспечить некоторую автономность при выделении (и избежать раскрытия информации там, где это нежелательно) SID регистрируются диапазонами (SID range). Значения SID выделяются навсегда и не могут быть изменены. Элементы, введённые новым выпуском модуля YANG, добавляются к списку уже выделенных SID.
2.4. Участники и роли
В процессе разработки YANG можно выделить несколько сторон, имяющих отношение к модулю YANG.
module controller – контролёр модуля
Владелец модуля YANG, т. е. лицо (организация), контролирующее развитие модуля.registration entity – орган регистрации
Контролёр пространства имён модуля, в частности, префиксов, которые обычно применяются (неообязательная строна).module repository – репозиторий модулей
Сущность, предоставляющая модули их пользователям. Это может быть «официальный» (например, IANA для модулей IETF) или «неофициальный» орган (например, каталог YANG [yangcatalog]). Не все репозитории могут выступать в роли реестра, т. е. постоянного хранилища записей для предоставляемой информации. Репозитории могут обращаться к владельцам модулей как стабильному источнику сведений.module user – пользователь модуля
Субъект, использующий модуль после его получения от контролёра или из репозитория.Этот набор сторон нужно расширить с учётом дополнительных ролей, требуемых для процесса назначения SID.
SID assigner – назначающий SID орган (сущность)
Орган, назначающих SID для модуля. Цель 2 состоит в том, чтобы для каждого модуля SID назначал лишь один орган. Желательно, чтобы назначающий SID орган не менялся в процессе разработки модуля, однако данная спецификация определяет файлы .sid для обеспечения организованной передачи.SID range registry – реестр диапазонов SID
Орган, которыя предоставляет назначающему SID органу диапазоны SID для выделения SID модулям. В данной спецификации имеется структура с мегадиапазонами (Mega-Range) и индивидуальными диапазонами SID.SID repository – репозиторий SID
Сущность, предоставляющая назначенные SID их пользователям (обычно в форме файла .sid).SID user – пользователь SID
Пользователь модуля, которые применяет SID, предоставленные назначающим SID органом для модуля YANG. Пользователям SID требуется найти назначившие SID органы или выделенные значения SID.По мере внедрения SID в модели данных YANG распределение ролей между имеющимися сторонами для модуля YANG будет развиваться. Желаемое финальное состояние этого развития показано в таблице 1.
Таблица . Стороны и роли – желаемое финальное состояние.
|
Роль |
Сторона |
|---|---|
|
Назначающий SID орган |
Разработчик модуля |
|
Реестр диапазонов SID |
В соответствии с данной спецификацией |
|
Репозиторий SID |
Репозиторий модулей |
|
Пользователь SID |
Пользователь модуля |
Такое распределение ролей позволяет разработчику модуля достигнуть целей, указанных в этом разделе (контролёр модуля руководящий SID, тип 1). Хотя теоретически кто-то другой может назначить дополнительные SID в противоречие цели 2, для этого будет мало причин, если разработчик модуля всегда предоставляет вместе с модулем файл .sid.
Остальная часть раздела посвящена переходу в желаемое финальное состояние.
Для существующих модулей нет файлов .sid и орган, выделяющий SID не указан. В такой ситуации наиболее вероятен конфликт с целью 2. При разработке нового модуля его создатели могут ещё не знать о SID или не быть заинтересованными в их назначении (например, из-за отсутствия в организации нужных программ или процедур).
Для этих двух случаев (контролёр модуля, безразличный к SID, тип 3) репозитории модулей могут послужить посредником, предоставляющим пользователям SID доступ к назначающему SID, который тщательно выбирается, чтобы его можно было использовать и другим репозиториям для повышения вероятности достижение цели 2.
Если контролёр модуля знает о SID, но пока не назначает их, он может указать назначающего SID вместо себя. Это может привести к тому, что стабильный набор уникальных SID будет назначаться разработчиком модуля опосредованно (знающий о SID контролёр, тип 2). Органы, предлагающие услуги назначенного SID-ассистента, могут обеспечивать обслуживание удобным способом, например, через web-интерфейс.
Назначающий SID орган должен, по меньшей мере, зарезервировать диапазон SID, который он будет использовать для назначения SID. Если используемый реестр диапазонов SID может записывать имена и выпуски модулей и процессы назначения (включая применяемые программы) стабильны, назначающий SID орган теоретически может реконструировать свои назначения, но это может вызвать ошибки в реализациях.
Назначающий SID орган, имеющий дело с разрабатываемым (ещё нестабильным) модулей, должен решить, назначать ли SID для нового выпуска «с нуля» (с чистого листа) или использовать имеющиеся назначения из предыдущего выпуска как базу и назначать новые SID только для новых имён. Когда модуль сочтён стабильным, назначенные для него SID также следует объявить стабильными (с учётом того, что для имеющихся модулей YANG может потребоваться тот или иной пересмотр).
В данной спецификации не рассматривается работа органов-посредников, таких как назначенные распределители SID или репозитории SID, указаны лишь цели действий таких органов.
3. Жизненный цикл файла .sid
Язык YANG предназначен для моделирования данных, доступ к которым осуществляется по одному из совместимых протоколов, например, NETCONF [RFC6241], RESTCONF [RFC8040], CORECONF (CoAP Management Interface) [CORE-COMI]). Модули YANG задают иерархии данных, включая данные конфигурации и состояния, RPC, действия и уведомления. Многие модули YANG создаются вне контекста приложений с ограничениями. Модули YANG можно реализовать с использованием NETCONF [RFC6241] или RESTCONF [RFC8040] без необходимости назначать SID.
При необходимости авторы модулей YANG могут присваивать SID для своих модулей. Для этого им следует сначала получить диапазон SID из реестра, а затем использовать этот диапазон для назначения или генерации SID для элементов их модулей YANG. Выделенные идентификаторы могут сохраняться в файле .sid. Пример реализации этого представлен в Приложении C.
Элементы, введённые новым выпуском модуля YANG, добавляются в список уже выделенных SID. Когда это происходит в процессе создания документа по новому протоколу, может потребоваться предварительное назначение идентификаторов, которые могут быть изменены, пересмотрены или отозваны во время разработки нового стандарта. Такие предварительные назначения получают статус нестабильных, чтобы их можно было удалить, а SID потом заново выделить для другого имени/пути схемы YANG в процессе разработки. Когда спецификация становится завершённым документом, назначенные идентификаторы получают статус стабильных. В процессе разработки, начиная с момента публикации спецификации, для средств разработки следует делать доступными два варианта файла .sid: (1) «общедоступный файл» файл .sid, содержащий только стабильные (в том числе в процессе разработки) SID, и «непубличный», который содержит нестабильные назначения SID.
Регистрация файла .sid, связанного с модулем YANG не требуется, но рекомендуется и будет способствовать функциональной совместимости устройств, а также позволит избежать дублирования SID для одного модуля YANG. Реестры могут предъявлять разные требования к регистрации и публикации файлов .sid. В качестве одного из вариантов может служить диаграмма действий на рисунке 4 в Приложении C.
При каждом обновлении модуля YANG, его субмодулей или импортируемых модулей может создаваться новый файл .sid, если новым или измененным элементам нужны SID. Все SID из прежней версии файла .sid, которая активно применялась, должны присутствовать в новаой версии файла. Создавать новые версии файлов .sid следует с помощью автоматизированных инструментов.
Если для новой версии требуется больше SID, чем было выделено изначально, в элемент assignment-range (раздел 4) должен добавляться новый диапазон SID. Эти SID применяются для последующих назначений. Пример процесса обновления представлен на рисунке 5 в Приложении C.
4. Формат файла .sid
Файлы .sid применяются для хранения и публикации SID, выделенных элементам YANG в конкретном модуле YANG. На рисунке 1 представлено дерево [BCP215], иллюстрирующее модель данных.
module: ietf-sid-file
structure sid-file:
+-- module-name yang:yang-identifier
+-- module-revision? revision-identifier
+-- sid-file-version? sid-file-version-identifier
+-- sid-file-status? enumeration
+-- description? string
+-- dependency-revision* [module-name]
| +-- module-name yang:yang-identifier
| +-- module-revision revision-identifier
+-- assignment-range* [entry-point]
| +-- entry-point sid
| +-- size uint64
+-- item* [namespace identifier]
+-- status? enumeration
+-- namespace enumeration
+-- identifier union
+-- sid sid
Рисунок . Дерево YANG для ietf-sid-file.
Ниже представлен модуль YANG, определяющий структуру файлов .sid. Кодирование выполняется в формате JSON [STD90] по правилам, заданным в [RFC7951]. Этот модуль импортирует ietf-yang-types [RFC6991] и ietf-yang-structure-ext [RFC8791], а также ссылается на [STD68], [RFC7950] и [BCP216].
<CODE BEGINS> file "ietf-sid-file@2024-07-31.yang"
module ietf-sid-file {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-sid-file";
prefix sid;
import ietf-yang-types {
prefix yang;
reference
"RFC 6991: Common YANG Data Types";
}
import ietf-yang-structure-ext {
prefix sx;
reference
"RFC 8791: YANG Data Structure Extensions";
}
organization
"IETF CORE Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/core/>
WG List: <mailto:core@ietf.org>
Editor: Michel Veillette
<mailto:michel.veillette@trilliant.com>
Editor: Andy Bierman
<mailto:andy@yumaworks.com>
Editor: Alexander Pelov
<mailto:alexander.pelov@imt-atlantique.fr>
Editor: Ivaylo Petrov
<mailto:ivaylopetrov@google.com>";
description
"Этот модуль определяет структуру файлов .sid.
Каждый файл .sid содержит сопоставление строковых идентификаторов
модуля YANG с соответствующими числовыми значениями YANG SID.
Ключевые слова ДОЛЖНО, НЕДОПУСТИМО, ТРЕБУЕТСЯ, НУЖНО, НЕ НУЖНО,
СЛЕДУЕТ, НЕ СЛЕДУЕТ, РЕКОМЕНДУЕТСЯ, НЕ РЕКОМЕНДУЕТСЯ, МОЖНО,
НЕОБЯЗАТЕЛЬНО в этом документе трактуются в соответствии с
BCP 14 (RFC 2119) (RFC 8174) тогда и только тогда, когда они
указаны заглавными буквами, как показано здесь.
Авторские права (Copyright (c) 2024) принадлежат IETF Trust
и лицам, указанным в качестве авторов кода. Все права защищены.
Распространение и использование в исходной или двоичной форме с
изменениями или без таковых разрешено в соответствии с лицензией
Simplified BSD, изложенной в разделе 4 IETF Trust's Legal
Provisions применительно к документам IETF
(http://trustee.ietf.org/license-info).
Эта версия данного модуля YANG является частью RFC 9595, где
правовые вопросы рассмотрены более полно.";
revision 2024-07-31 {
description
"Исходный выпуск.";
reference
"RFC 9595: YANG Schema Item iDentifier (YANG SID)";
}
typedef revision-identifier {
type string {
pattern '[0-9]{4}-[0-9]{2}-[0-9]{2}';
}
description
"Дата в формате YYYY-MM-DD.";
}
typedef sid-file-version-identifier {
type uint32;
description
"Версия файла .sid.";
}
typedef sid {
type uint64 {
range "0..9223372036854775807";
}
description
"Идентификатор элемента схемы YANG.";
reference
"RFC 9595: YANG Schema Item iDentifier (YANG SID)";
}
typedef schema-node-path {
type string {
pattern
'/[a-zA-Z_][a-zA-Z0-9\-_.]*:[a-zA-Z_][a-zA-Z0-9\-_.]*' +
'(/[a-zA-Z_][a-zA-Z0-9\-_.]*(:[a-zA-Z_][a-zA-Z0-9\-_.]*)?)*';
}
description
"Путь к узлу схемы - это абсолютный идентификатор узла схемы
YANG, по правилу YANG ABNF absolute-schema-nodeid, но с
использованием имён модулей вместо префиксов.
К этой строке дополнительно применяются указанные ниже правила
- самое левое (верхний уровень) имя узла данных всегда
указывается с пространством имён (namespace-qualified);
- любое последующее имя узла схемы имеет форму namespace-
qualified, если узел определён в модуле, отличном от
родительского, и простую форму в иных случаях. Предикаты
не разрешены";
reference
"RFC 5234 (STD 68): Augmented BNF for Syntax Specifications:
ABNF
RFC 7950: The YANG 1.1 Data Modeling Language,
Section 6.5: Schema Node Identifier";
}
sx:structure sid-file {
uses sid-file-contents;
}
grouping sid-file {
description
"Группировка с контейнером YANG, представляющим структуру
файла .sid.";
container sid-file {
description
"Контейнер-оболочка, который вместе с расширением
sx:structure маркирует находящиеся в нем структуры данных
YANG как не предназначенные для реализации в виде части
хранилища конфигурации или рабочего состояния на сервере.";
uses sid-file-contents;
}
}
grouping sid-file-contents {
description
"Группировка, задающая содержимое контейнера, представляющего
структуру файла .sid.";
leaf module-name {
type yang:yang-identifier;
mandatory true;
description
"Имя модуля YANG, связанного с файлом .sid.";
}
leaf module-revision {
type revision-identifier;
description
"Выпуск модуля YANG, связанного с этим файлом .sid. Этот лист
отсутствует, если в модуле YANG нет оператора revision.";
}
leaf sid-file-version {
type sid-file-version-identifier;
default 0;
description
"Необязательный лист, указывающий номер версии файла .sid.
Нумерация версий определяется конкретным выпуском модуля
YANG, начинается с 0 для первого выпуска и далее возрастает
монотонно. Значение позволяет различать обновления файла
.sid, например, в результате обработки или исправления
найденных ошибок.";
}
leaf sid-file-status {
type enumeration {
enum unpublished {
description
"Этот файл .sid не является общедоступным (BCP 216) и
называется рабочим. Он может сопровождать непубличный
модуль YANG. Список item МОЖЕТ включать записи со
статусом unstable.";
reference
"RFC 8407 (BCP 216): Guidelines for Authors and
Reviewers of Documents Containing
YANG Data Models";
}
enum published {
description
"Этот файл .sid является опубликованным. Такой статус
применяется к файлам .sid для опубликованных модулей
YANG. В список item НЕДОПУСТИМО включать записи со
статусом unstable.";
}
}
default "published";
description
"Необязательный лист, указывающий статус файла .sid.";
}
leaf description {
type string;
description
"Метаинформация о сгенерированном файле в произвольной форме.
Може указывать инструмент, создавший файл .sid, время
генерации и другие данные.";
}
list dependency-revision {
key "module-name";
description
"Сведения о выпусках, использованных при генерации файла .sid
для каждой зависимости, т. е. для каждого модуля YANG,
импортируемого связанным в файлом .sid модулем YANG.";
leaf module-name {
type yang:yang-identifier;
description
"Имя модуля YANG для данной зависимости.";
}
leaf module-revision {
type revision-identifier;
mandatory true;
description
"Выпуск модуля YANG для данной зависимости .";
}
}
list assignment-range {
key "entry-point";
description
"Диапазоны YANG-SID, выделенные модулю YANG, указанному
module-name и module-revision.
- Первое значение диапазона YANG-SID - это entry-point,
последнее - (entry-point + size - 1).
- НЕДОПУСТИМО перерытие диапазонов assignment-range.";
leaf entry-point {
type sid;
description
"Наименьшее значение YANG SID для выделения.";
}
leaf size {
type uint64;
mandatory true;
description
"Число YANG SID, доступных для выделения.";
}
}
list item {
key "namespace identifier";
unique "sid";
description
"Каждая запись списка сопоставляет строку идентификатора YANG
с YANG SID. Список ДОЛЖЕН включать сопоставления для всех
элементов YANG, заданных в модуле, указанном в module-name и
module-revision.";
leaf status {
type enumeration {
enum stable {
value 0;
description
"Это назначение SID опубликовано как стабильное для
данного пространства имён и идентификатора.";
}
enum unstable {
value 1;
description
"Это назначение SID выполнено в процессе разработки
и ещё не является стабильным.";
}
enum obsolete {
value 2;
description
"Это значение SID больше не используется и указано для
предотвращения повторного выделения.";
}
}
default "stable";
description
"Сведения о стабильности назначения. Каждое конкретное
значение SID с течением времени может переходить из
состояния unstable в stable, а stable может смениться на
obsolete.";
}
leaf namespace {
type enumeration {
enum module {
value 0;
description
"Все имена в модуле и субмодулях используют глобальное
пространство имён идентификаторов этого модуля.";
}
enum identity {
value 1;
description
"Все имена идентификаторов в модуле и его субмодулях
используют некое общее пространство имен.";
}
enum feature {
value 2;
description
"Все имена свойств (feature) в модуле и его субмодулях
используют некое общее пространство имен.";
}
enum data {
value 3;
description
"Пространство имён всех узлов данных задано в YANG.";
}
}
description
"Пространство имён для элемента YANG в этом отображении.";
}
leaf identifier {
type union {
type yang:yang-identifier;
type schema-node-path;
}
description
"Строковый идентификатор элемента YANG в этой записи. Если
соответствующее поле namespace имеет значение module,
feature, или identity, это поде ДОЛЖНО содержать
действительный идентификатор YANG. Если поле namespace
имеет значение data, поле ДОЛЖНО содержать действительный
путь к узлу схемы YANG.";
}
leaf sid {
type sid;
mandatory true;
description
"Значение YANG SID, выделенное элементу YANG.";
}
}
}
}
<CODE ENDS>
Рисунок . Модуль YANG ietf-sid-file.
5. Вопросы безопасности
Этот документ определяет новый тип идентификатора, применяемый для кодирования данных, моделируемых в YANG [RFC7950]. Новый идентификатор сопоставляет семантические поняти с целыми числами и при отсутствия доверия к источнику отображения могут возникать новые риски безопасности, если злоумышленник контролирует отображение.
На момент написания документа предполагалось, что файлы .sid обрабатываются разработчиками программ в среде разработки. Разработчикам рекомендуется импортировать файлы .sid только из полномочных источников. Для поддерживаемых IETF модулей YANG полномочным источником является IANA.
Файлы .sid могут обрабатываться и менее ограниченными целевыми системами, например, системами управления сетью. Таким системам нужно быть особенно внимательными и обеспечивать обработку лишь файлов .sid из полномочных источников, доверие к которым не ниже уровня доверия к используемым модулям YANG.
Файлы .sid указываются ссылочными идентификаторами и могут включать их, т. е. такие идентификаторы в определённых ситуациях могут автоматически организовать удалённый доступ, цель которого хотя бы частично указывается соответствующим идентификатором. Это может предоставить злоумышленникам сведения о таком доступе и даже контроль над ним, что может повлиять на приватность и безопасность. Дополнительные сведения по этим вопросам представлены в разделах 6 и 7 [DEREF-ID].
6. Взаимодействие с IANA
6.1. Регистрация пространства имён YANG
Этот документ регистрирует пространство имён XML URN в реестре IETF XML Registry в соответствии с [BCP81].
URI: urn:ietf:params:xml:ns:yang:ietf-sid-file Registrant Contact: The IESG. XML: N/A; регистрируемый URI является пространством имён XML. Reference: RFC 9595
6.2. Регистрация модуля формата файла .sid
Этот документ регистрирует модуль YANG в реестре YANG Module Names [RFC6020].
Name: ietf-sid-file Namespace: urn:ietf:params:xml:ns:yang:ietf-sid-file Prefix: sid Reference: RFC 9595
6.3. Новый реестр IANA YANG-SID Mega-Ranges
Реестр YANG-SID Mega-Ranges служит для записей о передаче полномочий управления блоками SID тем или иным организациям, например, органам стандартизации (Standards Development Organization или SDO) или регистраторам.
6.3.1. Структура
Каждая запись реестра должна включать:
-
начальную точку (первый SID) зарегистрированного блока SID;
-
размер зарегистрированного блока SID (следует выделять блоки по 1 миллиону SID, но в исключительных случаях можно выделять кратные миллиону блоки);
-
политика выделения SID из блока (Public, Private или то и другое);
-
компактные сведений о запросившей блок организации, включая:
-
название организации;
-
URL.
-
6.3.2. Правила выделения
Для добавления в этот реестр используется процедура IANA Expert Review (параграф 4.5 в RFC 8126 [BCP26]).
Организация, желающая управлять диапазоном YANG-SID (иметь запись в реестре YANG-SID Mega-Ranges), должна иметь указанные ниже возможности.
-
Способность управлять и поддерживать реестр диапазонов YANG-SID, который должен обеспечивать для всех выделенных реестром диапазонов YANG-SID:
-
начальную точку выделенного диапазона YANG-SID;
-
размер выделенного диапазона YANG-SID;
-
тип (Public или Private).
-
Публичные диапазоны должны включать, по меньшей мере, ссылку на модуль YANG и файлы .sid для этого диапазона YANG-SID (в параграфе 6.4.3 дан пример для реестра IETF YANG-SID Ranges).
-
Частные диапазоны должны иметь метку Private.
-
-
-
Политика выделения, чётко указывающая, будет ли выделенный диапазон YANG-SID частным (Private), общедоступным (Public) или тем и другим сразу.
-
Техническая возможность предоставления файлов .sid или ссылок на них с обеспечением целостности данных в этих файлах (см. раздел 5).
-
Техническая возможность обеспечить стабильную работу реестра в течение, по меньшей мере, 5 лет. Если допускается регистрация в категории Private, этот период должен быть не мнее 10 лет.
Если желателен диапазон более 1 миллиона значений, организация дожна продемонстрировать устойчивость технического подхода к использованию такого блока, отсутствие негативного влияния на удобство использования механизмов выделения SID в целом. Такие блоки SID предпочтительно размещать в пространстве не менее 4295000000 (64 бита).
6.3.2.1. Первое выделение
Для первого выделения организация-заявитель должна продемонстрировать функциональную инфраструктуру реестра.
6.3.2.2. Последующее выделение
При последующем выделении диапазона организация должна продемонстрировать исчерпание выделенного ранее диапазона, что должно быть подтверждено назначенным экспертом (экспертами). Если запрос на дополнительное выделение подан не позднее 3 лет после предыдущего выделения, эксперты должны обсудить этот запрос в почтовой конференции рабочей группы CORE и достичь согласия по части выделения нового Mega-Range.
6.3.3. Исходное содержимое реестра
Таблица . Исходное содержимое реестра YANG-SID Mega-Ranges.
|
Начало |
Размер |
Выделение |
Организация |
URL |
|---|---|---|---|---|
|
0 |
1 000 000 |
Public |
IANA |
6.4. Новый реестр IANA IETF YANG-SID Ranges
Реестр IETF YANG-SID Ranges служит для записи сведений о назначений из диапазонов SID (например, начало и размер) для модулей YANG, указанных именем.
6.4.1. Структура
Каждая запись реестра должна включать:
-
начальное значение диапазона SID;
-
размер диапазона SID;
-
имя модуля YANG;
-
ссылку на документ, на основании которого выполняется регистрация.
6.4.2. Правила выделения
Первый миллион SID, выделенных IANA поделён, как показано ниже.
-
Значения от 0 до 999 (размер 1000) выделяются по процедуре IESG Approval, заданной в параграфе 4.10 и RFC 8126 [BCP26], при этом значение 0 зарезервировано для реализаций, указывающих отсутствие SID, и не применяется в обмене.
-
Значения от 1000 до 59999 (размер 59000) и от 100000 до 299999 (размер 200000) предназначены для модулей YANG, заданных в RFC.
-
Процедуры IANA для добавления в реестр указаны ниже.
-
Expert Review (параграф 4.5 в RFC 8126 [BCP26]), если файл .sid происходит из модуля YANG, заданного имеющимся RFC.
-
RFC Required (параграф 4.7 в RFC 8126 [BCP26]) в ином случае.
-
-
Эксперт должен убедиться, что модуль YANG, для которого выделяются значения, опубликован в RFC или документ находится в стадии публикации RFC (раннее выделение по запросу от руководителей рабочей группы, как указано в [BCP100]).
-
-
Значения от 60000 до 99999 (размер 40000) зарезервированы для экспериментальных модулей YANG. Этот диапазон недопустимо использоваться в рабочих системах, поскольку SID из него не являются глобально уникальными и их функциональная совместимость ограничена. Для выделения значений применяется процедура IANA Experimental Use (параграф 4.2 в RFC 8126 [BCP26]).
-
Диапазон от 300000 до 999999 (размер 700000) является резервным, как указано в разделе 6 RFC 8126 [BCP26].
Таблица . Реестр IETF YANG-SID Ranges, правила для диапазонов IETF.
|
Начало |
Размер |
Процедура IANA |
|---|---|---|
|
0 |
1000 |
IESG Approval |
|
1000 |
59000 |
RFC и Expert Review (см. п. 2) |
|
60000 |
40000 |
Experimental Use |
|
100000 |
200000 |
RFC и Expert Review (см. п. 2) |
|
300000 |
700000 |
Reserved |
Размер диапазона SID, выделяемого модулю YANG, рекомендуется делать кратным 50 и по меньшей мере на 33% больше числа имеющихся в модуле элементов YANG. Это позволит выделять новым элементам YANG идентификаторы из имеющегося запаса. Размер диапазона SID не следует делать больше 1000, но авторы модуля могут запросить больший размер при необходимости. Важно отметить, что имеющемуся модулю YANG может быть выделен дополнительный диапазон SID, если исходный диапазон исчерпан. Это ведёт лишь к некоторому снижению эффективности представления.
Если диапазон SID выделяется для имеющегося RFC по процедуре Expert Review (параграф 4.5 в RFC 8126 [BCP26]), в поле Reference для этой записи следует указывать RFC, где определён модуль YANG.
Если диапазон SID требуется до публикации RFC, поскольку реализациям нужны стабильные SID, для процедуры RFC Required может применять раннее выделение (Early Allocation, раздел 2 в RFC 7120 [BCP100]).
6.4.3. Публикация файла .sid
В процессе публикации RFC IANA связывается с назначенными экспертами (команда), отвечающими за предоставление окончательного файла .sid для каждого модуля, определённого в этом RFC. Для разработчиков типа 3 (SID-oblivious, см. параграф 2.4) команда создаёт файл .sid из каждого модуля YANG (см. ниже). Для разработчиков типа 2 (SID-aware) команда сначала получает черновой файл .sid по стабильной ссылке в одобренном проекте, для разработчиков типа 1 (SID-guiding) файл .sid берётся из одобренного черновика. Команда использует инструменты для создания окончательного файла .sid по каждому из модулей YANG, в котором все назначения SID имеют статус stable, а сам файл .sid имеет статус published. В опубликованном файле .sid недопустимы SID со статусом unstable.
Кроме случаев типа 3 (SID-oblivious) команда подаёт имеющийся черновик .sid на вход используемого инструмента (опорный файл), чтобы изменения при повторной генерации были минимальными. Для модулей YANG, являющихся новым выпуском опубликованного ранее модуля имеющийся опубликованный файл .sid должен применяться в качестве опорного для инструмента при генерации пересмотренного чернового (типы 1 и 2) или окончательного (тип 3) файла .sid.
В любой случае команда проверяет сгенерированный файл, включая проверку пригодности для использования в качестве .sid, соответствия диапазону SID, полного охвата элементов из модуля YANG и максимально возможного соответствия имеющемуся черновому файлу .sid.
Затем назначенные эксперты передают файл .sid в IANA для публикации в реестре IETF YANG-SID Modules (параграф 6.5) вместе с модулем YANG.
Недопустимо публиковать файл .sid как часть RFC. Реестр IANA является полномочным и ссылка на него включается в RFC (данный RFC является исключением из этого правила, поскольку файл .sid в нем служит для иллюстрации). Документы Internet-Draft, которым требуются SID для новых модулей, используемые в тексте документа (скажем, для примеров), должны указать это редактору RFC в тексте чернового документа. Такие RFC не могут создавать разработчики типа 3 (SID-oblivious), SID, используемые в тексте, должны быть назначены в имеющемся черновом файле .sid, а команда экспертов должна проверить согласованность назначения в окончательном файле .sid и использования идентификаторов в тексте RFC или соответствующего одобренного черновика.
6.4.4. Исходное содержимое реестра
Таблица . Реестр IETF YANG-SID Ranges, исходное выделение.
|
Начало |
Размер |
Имя модуля |
Документ |
|---|---|---|---|
|
0 |
1 |
Резерв, не является действительным SID |
RFC 9595 |
|
1000 |
100 |
ietf-coreconf |
RFC 9595, [CORE-COMI] |
|
1100 |
50 |
ietf-yang-types |
[RFC6991] |
|
1150 |
50 |
ietf-inet-types |
[RFC6991] |
|
1200 |
50 |
iana-crypt-hash |
[RFC7317] |
|
1250 |
50 |
ietf-netconf-acm |
[STD91] |
|
1300 |
50 |
ietf-sid-file |
RFC 9595 |
|
1500 |
100 |
ietf-interfaces |
[RFC8343] |
|
1600 |
100 |
ietf-ip |
[RFC8344] |
|
1700 |
100 |
ietf-system |
[RFC7317] |
|
1800 |
400 |
iana-if-type |
[RFC7224] |
Для выделения диапазона требуется публикация RFC с модулем YANG в соответствии с процедурой RFC Required, заданной в параграфе 4.7 RFC 8126 [BCP26]. Модуль YANG должен регистрироваться в реестре YANG Module Names по правилам, заданным в разделе 14 [RFC6020].
6.5. Новый реестр IANA IETF YANG-SID Modules
Реестр IETF YANG-SID Modules служит для записи выделения SID элементам отдельных модулей YANG.
6.5.1. Структура
Каждая запись реестра должна включать:
-
имя модуля YANG, которое должно быть представлено в столбце Name реестра YANG Module Names;
-
URI связанного файле .yang, который должен быть указан в столбце File реестра YANG Module Names;
-
URI файла .sid, определяющего выделение идентификаторов (файл .sid сохраняется агентством IANA);
-
число фактически выделенных в файле .sid идентификаторов SID.
6.5.2. Правила выделения
Выделение происходит по процедуре Expert Review (параграф 4.5 в RFC 8126 [BCP26]). Эксперты должны обеспечить выполнение указанных ниже условий.
-
Файл .sid имеет корректную структуру:
-
файл .sid должен быть корректным файлом JSON, соответствующим структуре заданного здесь модуля.
-
-
Файл .sid назначает индивидуальные SID только из диапазонов YANG-SID для данного модуля YANG (как указано в реестре IETF YANG-SID Ranges):
-
все SID в файле .sid должны относиться к диапазонам, выделенным данному модулю YANG в реестре IETF YANG-SID Ranges.
-
-
Если другой файл .sid уже содержит SID для этого модуля YANG (например, для других версий модуля), элементам YANG присваиваются SID, которые уже указаны в том файле .sid.
-
Если имеется более старая версия файла .sid, выделенные в нем SID включаются в текущий файл.
6.5.3. Рекурсивное выделение YANG SID при принятии документа
Из-за сложности смены значений SID в процессе обработки документа в IETF ожидается, для для большинства it документов будет запрашиваться выделение SID заранее (Early Allocation [BCP100]). Детали раннего выделения, включая предполагаемые сроки, следует включать в запрос на принятие документа рабочей группой. До принятия проекта документа (Internet-Draft) рабочей группой авторы могут использовать SID из диапазона для экспериментов (см. параграф 6.4.2) или иные значения, не вызывающие путаницы с другими SID (например, можно использовать диапазоны из реестров, не управляемых IANA, которые основаны на выделении YANG-SID Mega-Range).
Предполагается, что после принятия рабочей группой любые изменения файла .sid обсуждаются в списке рассылки этой группы. Особое внимание следует уделять мнениям внедряющих после Working Group Last Call, если значение SID меняет смысл. Во всех случаях файл .sid и связанные с ним SID можно изменить до публикации Internet-Draft как RFC.
Поскольку концепция SID применяется впервые, для опубликованных ранее модулей YANG значения SID не выделены. Чтобы назначение было полезным, для включённых модулей YANG также может потребоваться выделение SID в процессе, который обычно будет аналогичен процессу из параграфа 6.4.3 для типа 3 (SID-oblivious).
Эксперты, анализирующие (ранее) назначение, должны просмотреть список включённых модулей YANG и выделить для них SID.
-
Если документ опубликован как RFC, выделение SID для ссылающихся на него модулей YANG будет постоянным. Эксперт-рецензент предоставляет сгенерированный файл .sid в IANA для регистрации.
-
Если документ является необработанным Internet-Draft, принятым рабочей группой, для него применяется раннее выделение, которое требует одобрения руководителем направления IESG. Ранее выделение, требующее дополнительных назначений, будет включать в своё описание список таких выделений, который будет передаваться в списки рассылки затрагиваемых рабочих групп.
-
Модуль YANG, ссылающийся на модуль из документа, который ещё не принят рабочей группой, не может получить раннее выделение для этого документа, пока тот не будет принят рабочей группой. Как указано в разделе 3 RFC 7120 [BCP100], курирующий директор направления (AD) будет выступать в роли руководителя рабочей группы, если документ не является результатом работы группы IETF, что фактически позволяет AD обойти применение для документа этого правила.
В конце процесса IETF всем зависимостям модуля, для которого выделяются SID, также следует иметь SID. Эти назначения следует делать постоянными (не Early Allocation).
Модуль YANG с выделенными ранее SID, который меняет свои ссылки, включая модуль YANG, ещё не имеющий SID, должен повторить процедуру Early Allocation.
В [BCP100] задан срок действия Early Allocation, по истечении которого выделение теряет силу, если оно не возобновлено. В параграфе 3.3 RFC 7120 [BCP100] также сказано:
Отметим, что для случаев, когда документ представлен на рассмотрение IESG и на момент подачи срок действия Early Allocation ещё не истёк, назначения не будут считаться просроченными, пока документ рассматривается в IESG или ожидает публикации в очереди RFC Editor после одобрения IESG.
6.5.4. Исходное содержимое реестра
На момент написания этого документа в реестре ещё не было записей.
6.6. Регистрация типа носителя и формата содержимого
6.6.1. Тип носителя application/yang-sid+json
Этот документ добавляет описанный ниже тип носителя в реестр Media Types.
Таблица . Регистрация типа носителя для файлов .sid.
|
Имя |
Шаблон |
Документ |
|---|---|---|
|
yang-sid+json |
application/yang-sid+json |
RFC 9595 |
Type name: application
Subtype name: yang-sid+json
Required parameters: N/A
Optional parameters: N/A
Encoding considerations: binary (UTF-8)
Security considerations: см. раздел 5 в RFC 9595.
Published specification: RFC 9595
Applications that use this media type: Приложения, которым нужны YANG
SID для обмена данными YANG с компактным представлением.
Fragment identifier considerations: Синтаксис и семантика
идентификаторов фрагментов для application/yang-sid+json совпадают
с заданными для application/json (на момент публикации документа
синтаксис для application/json не был задан).
Additional information:
Magic number(s): N/A
File extension(s): .sid
Macintosh file type code(s): N/A
Person & email address to contact for further information: список
рассылки CORE WG (core@ietf.org) или IETF Applications and
Real-Time Area (art@ietf.org).
Intended usage: COMMON
Restrictions on usage: нет
Author/Change controller: IETF
6.6.2. Формат содержимого CoAP
Этот документ добавляет указанный в таблице 6 формат содержимого (Content-Format) в реестр CoAP Content-Formats группы реестров Constrained RESTful Environments (CoRE) Parameters, со значением 260 из диапазона IETF Review (256 – 9999) (см. параграф 4.8 в RFC 8126 [BCP26]).
Таблица . Регистрация формата содержимого для файлов .sid.
|
Тип содержимого |
Кодирование содержимого |
ID |
Документ |
|---|---|---|---|
|
application/yang-sid+json |
– |
260 |
RFC 9595 |
7. Литература
7.1. Нормативные документы
[BCP100] Best Current Practice 100, <https://www.rfc-editor.org/info/bcp100>. At the time of writing, this BCP comprises the following: Cotton, M., “Early IANA Allocation of Standards Track Code Points”, BCP 100, RFC 7120, DOI 10.17487/RFC7120, January 2014, <https://www.rfc-editor.org/info/rfc7120>.
[BCP14] Best Current Practice 14, <https://www.rfc-editor.org/info/bcp14>. At the time of writing, this BCP comprises the following:
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>.
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>.
[BCP81] Best Current Practice 81, <https://www.rfc-editor.org/info/bcp81>. At the time of writing, this BCP comprises the following: Mealling, M., “The IETF XML Registry”, BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[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>.
[RFC7951] Lhotka, L., “JSON Encoding of Data Modeled with YANG”, RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.
[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>.
[RFC8791] Bierman, A., Björklund, M., and K. Watsen, “YANG Data Structure Extensions”, RFC 8791, DOI 10.17487/RFC8791, June 2020, <https://www.rfc-editor.org/info/rfc8791>.
[STD68] Internet Standard 68, <https://www.rfc-editor.org/info/std68>. At the time of writing, this STD comprises the following: Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, STD 68, RFC 5234, DOI 10.17487/RFC5234, January 2008, <https://www.rfc-editor.org/info/rfc5234>.
[STD90] Internet Standard 90, <https://www.rfc-editor.org/info/std90>. At the time of writing, this STD comprises the following: Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”, STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/info/rfc8259>.
7.2. Дополнительная литература
[BCP215] Best Current Practice 215, <https://www.rfc-editor.org/info/bcp215>. At the time of writing, this BCP comprises the following: 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>.
[BCP216] Best Current Practice 216, <https://www.rfc-editor.org/info/bcp216>. At the time of writing, this BCP comprises the following: Bierman, A., “Guidelines for Authors and Reviewers of Documents Containing YANG Data Models”, BCP 216, RFC 8407, DOI 10.17487/RFC8407, October 2018, <https://www.rfc-editor.org/info/rfc8407>.
[BCP26] Best Current Practice 26, <https://www.rfc-editor.org/info/bcp26>. At the time of writing, this BCP comprises the following: Cotton, M., Leiba, B., and T. Narten, “Guidelines for Writing an IANA Considerations Section in RFCs”, BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, <https://www.rfc-editor.org/info/rfc8126>.
[CORE-COMI] Veillette, M., Ed., van der Stok, P., Ed., Pelov, A., Ed., Bierman, A., and C. Bormann, Ed., “CoAP Management Interface (CORECONF)”, Work in Progress, Internet-Draft, draft-ietf-core-comi-18, 23 July 2024, <https://datatracker.ietf.org/doc/html/draft-ietf-core-comi-18>.
[DEREF-ID] Bormann, C. and C. Amsüss, “The ‘dereferenceable identifier’ pattern”, Work in Progress, Internet-Draft, draft-bormann-t2trg-deref-id-03, 2 March 2024, <https://datatracker.ietf.org/doc/html/draft-bormann-t2trg-deref-id-03>.
[PYANG] Björklund, M., “An extensible YANG validator and converter in python”, commit fc9a965, May 2024, <https://github.com/mbj4668/pyang>.
[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>.
[RFC7224] Bjorklund, M., “IANA Interface Type YANG Module”, RFC 7224, DOI 10.17487/RFC7224, May 2014, <https://www.rfc-editor.org/info/rfc7224>.
[RFC7228] Bormann, C., Ersue, M., and A. Keranen, “Terminology for Constrained-Node Networks”, RFC 7228, DOI 10.17487/RFC7228, May 2014, <https://www.rfc-editor.org/info/rfc7228>.
[RFC7317] Bierman, A. and M. Bjorklund, “A YANG Data Model for System Management”, RFC 7317, DOI 10.17487/RFC7317, August 2014, <https://www.rfc-editor.org/info/rfc7317>.
[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>.
[RFC8792] Watsen, K., Auerswald, E., Farrel, A., and Q. Wu, “Handling Long Lines in Content of Internet-Drafts and RFCs”, RFC 8792, DOI 10.17487/RFC8792, June 2020, <https://www.rfc-editor.org/info/rfc8792>.
[RFC9195] Lengyel, B. and B. Claise, “A File Format for YANG Instance Data”, RFC 9195, DOI 10.17487/RFC9195, February 2022, <https://www.rfc-editor.org/info/rfc9195>.
[RFC9254] Veillette, M., Ed., Petrov, I., Ed., Pelov, A., Bormann, C., and M. Richardson, “Encoding of Data Modeled with YANG in the Concise Binary Object Representation (CBOR)”, RFC 9254, DOI 10.17487/RFC9254, July 2022, <https://www.rfc-editor.org/info/rfc9254>.
[STD91] Internet Standard 91, <https://www.rfc-editor.org/info/std91>. At the time of writing, this STD comprises the following: 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>.
[YANG-LIBRARY] Veillette, M., Ed. and I. Petrov, Ed., “Constrained YANG Module Library”, Work in Progress, Internet-Draft, draft-ietf-core-yang-library-03, 11 January 2021, <https://datatracker.ietf.org/doc/html/draft-ietf-core-yang-library-03>.
[yangcatalog] “YANG Catalog”, <https://yangcatalog.org>.
Приложение A. Пример файла .sid
Приведённый ниже файл .sid (ietf-system@2014-08-06.sid) создан с использованием модулей YANG:
-
ietf-system@2014-08-06.yang [RFC7317];
-
ietf-yang-types@2013-07-15.yang [RFC6991];
-
ietf-inet-types@2013-07-15.yang [RFC6991];
-
ietf-netconf-acm@2018-02-14.yang [STD91];
-
iana-crypt-hash@2014-08-06.yang [RFC7317].
В соответствии с [RFC8792] длинные строки JSON разделены символом \.
{
"ietf-sid-file:sid-file": {
"module-name": "ietf-system",
"module-revision": "2014-08-06",
"description": "Example '.sid' file",
"dependency-revision": [
{
"module-name": "ietf-yang-types",
"module-revision": "2013-07-15"
},
{
"module-name": "ietf-inet-types",
"module-revision": "2013-07-15"
},
{
"module-name": "ietf-netconf-acm",
"module-revision": "2018-02-14"
},
{
"module-name": "iana-crypt-hash",
"module-revision": "2014-08-06"
}
],
"assignment-range": [
{
"entry-point": "1700",
"size": "100"
}
],
"item": [
{
"namespace": "module",
"identifier": "ietf-system",
"sid": "1700"
},
{
"namespace": "identity",
"identifier": "authentication-method",
"sid": "1701"
},
{
"namespace": "identity",
"identifier": "local-users",
"sid": "1702"
},
{
"namespace": "identity",
"identifier": "radius",
"sid": "1703"
},
{
"namespace": "identity",
"identifier": "radius-authentication-type",
"sid": "1704"
},
{
"namespace": "identity",
"identifier": "radius-chap",
"sid": "1705"
},
{
"namespace": "identity",
"identifier": "radius-pap",
"sid": "1706"
},
{
"namespace": "feature",
"identifier": "authentication",
"sid": "1707"
},
{
"namespace": "feature",
"identifier": "dns-udp-tcp-port",
"sid": "1708"
},
{
"namespace": "feature",
"identifier": "local-users",
"sid": "1709"
},
{
"namespace": "feature",
"identifier": "ntp",
"sid": "1710"
},
{
"namespace": "feature",
"identifier": "ntp-udp-port",
"sid": "1711"
},
{
"namespace": "feature",
"identifier": "radius",
"sid": "1712"
},
{
"namespace": "feature",
"identifier": "radius-authentication",
"sid": "1713"
},
{
"namespace": "feature",
"identifier": "timezone-name",
"sid": "1714"
},
{
"namespace": "data",
"identifier": "/ietf-system:set-current-datetime",
"sid": "1715"
},
{
"namespace": "data",
"identifier": "/ietf-system:set-current-datetime/input",
"sid": "1775"
},
{
"namespace": "data",
"identifier": "/ietf-system:set-current-datetime/input/\
current-datetime",
"sid": "1776"
},
{
"namespace": "data",
"identifier": "/ietf-system:system",
"sid": "1717"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-restart",
"sid": "1718"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-shutdown",
"sid": "1719"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state",
"sid": "1720"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/clock",
"sid": "1721"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/clock/boot-datetime\
",
"sid": "1722"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/clock/current-\
datetime",
"sid": "1723"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/platform",
"sid": "1724"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/platform/machine",
"sid": "1725"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/platform/os-name",
"sid": "1726"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/platform/os-release\
",
"sid": "1727"
},
{
"namespace": "data",
"identifier": "/ietf-system:system-state/platform/os-version\
",
"sid": "1728"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication",
"sid": "1729"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user",
"sid": "1730"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user-\
authentication-order",
"sid": "1731"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/\
authorized-key",
"sid": "1732"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/\
authorized-key/algorithm",
"sid": "1733"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/\
authorized-key/key-data",
"sid": "1734"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/\
authorized-key/name",
"sid": "1735"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/name",
"sid": "1736"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/authentication/user/\
password",
"sid": "1737"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/clock",
"sid": "1738"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/clock/timezone-name",
"sid": "1739"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/clock/timezone-utc-offset\
",
"sid": "1740"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/contact",
"sid": "1741"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver",
"sid": "1742"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/options",
"sid": "1743"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/options/\
attempts",
"sid": "1744"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/options/\
timeout",
"sid": "1745"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/search",
"sid": "1746"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/server",
"sid": "1747"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/server/name",
"sid": "1748"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/server/udp-\
and-tcp",
"sid": "1749"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/server/udp-\
and-tcp/address",
"sid": "1750"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/dns-resolver/server/udp-\
and-tcp/port",
"sid": "1751"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/hostname",
"sid": "1752"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/location",
"sid": "1753"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp",
"sid": "1754"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/enabled",
"sid": "1755"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server",
"sid": "1756"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/association-\
type",
"sid": "1757"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/iburst",
"sid": "1758"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/name",
"sid": "1759"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/prefer",
"sid": "1760"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/udp",
"sid": "1761"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/udp/address",
"sid": "1762"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/ntp/server/udp/port",
"sid": "1763"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius",
"sid": "1764"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/options",
"sid": "1765"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/options/attempts",
"sid": "1766"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/options/timeout",
"sid": "1767"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server",
"sid": "1768"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/\
authentication-type",
"sid": "1769"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/name",
"sid": "1770"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/udp",
"sid": "1771"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/udp/address\
",
"sid": "1772"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/udp/\
authentication-port",
"sid": "1773"
},
{
"namespace": "data",
"identifier": "/ietf-system:system/radius/server/udp/shared-\
secret",
"sid": "1774"
}
]
}
}
Рисунок . Пример файла .sid (модуль ietf-system с переносом длинных строк).
Приложение B. Автоматическая генерация SID
Назначение SID для элементов YANG следует автоматизировать. Рекомендуемый процесс приведён ниже.
-
Инструмент извлекает элементы, заданные в конкретном модуле YANG.
-
Элементы сортируются по алфавиту с размещением записей namespace в порядке убывания, а identifier – в порядке возрастания. Формат namespace и identifier описан в модуле YANG ietf-sid-file, заданном в разделе 4.
-
Значения SID выделяются последовательно от начальной точки до максимального значения в зарегистрированном диапазоне SID. Этот подход рекомендуется для минимизации издержек на сериализацию, (delta) между опорным и текущим SID используется протоколами, нацеленными на снижение размера сообщений.
-
Если число элементов превышает размер диапазона SID, выделенного модулю YANG, добавляется ещё один диапазон для назначения.
-
В элементе списка dependency-revision следует отражать номера выпусков каждого импортируемого модуля YANG (на момент генерации).
При обновлении активно используемого модуля YANG имеющиеся назначения SID сохраняются, а при обновлении рабочей версии Internet-Draft, ещё не принятой сообществом, назначение SID лучше выполнять «с нуля». Если имя узла схемы меняется, а данные структурно и семантически схожи с доступными раньше по старому имени, SID для старого имени можно продолжать использовать с новым. Если меняется значение элемента, ему можно выделить новый SID, это особенно полезно для идентификации новой структуры и семантики элемента. Если тип данных YANG меняется в новом выпуске опубликованного модуля так, что в результате изменяется кодирование CBOR, реализация существенно упростится при назначении нового SID. Отметим, что такие решения обычно принимает автор модуля YANG, которому следует решить, нужно ли ручное вмешательство в процесс автоматического назначения.
При обновлении имеющегося файла .sid требуется дополнительный шаг для увеличения номера версии файла .sid. Если у прежнего файла не было номера версии, принимается значение 0 и новому файлу .sid присваивается номер версии 1. Изменения в файлах .sid можно автоматизировать с использованием приведённой выше схемы за исключением того, что в п. 3 сохраняются прежние назначения SID и обрабатываются только новые элементы YANG, которым назначаются SID. Имеющимся в файле .sid элементам не следует присваивать новые SID.
Отметим, что версия файла .sid специфична для выпуска модуля YANG т для каждого нового модуля YANG или нового выпуска имеющегося модуля начальному файлу .sid следует (1) задавать версию 0 или (2) не указывать версию.
Отметим, что элементам YANG input и output в RPC и action должны назначаться SID, даже если в них нет других элементов YANG. Причина этого заключается в том, что данный модуль может дополняться другими модулями, которым могут требоваться SID.
Приложение C. Жизненный цикл файла .sid
До назначения SID элементам модулей YANG авторы модуля должны получить диапазон SID из реестра YANG-SID Ranges. Если модуль YANG является частью IETF Internet-Draft или RFC, диапазон SID нужно получать из реестра IETF YANG-SID Ranges, как указано в параграфе 6.4. Для иных модулей YANG авторы могут получить диапазон SID из любого реестра YANG-SID Ranges.
После получения диапазона SID его владельцы могут использовать диапазон для генерации одного или нескольких файлов .sid для своих модулей YANG. Рекомендуется оставлять некоторое число нераспределенных SID после выделенного для файла .sid блока, чтобы упростить будущее развитие модулей YANG. Создавать файлы .sid с помощью автоматизированных инструментов. Отметим, что файлы .sid создаются лишь для модулей YANG (не субмодулей).
C.1. Создание файла .sid
+---------------+
o | Создание |
-+- -->| модуля YANG |
/ \ +------+--------+
|
v
.-------------.
/ Стандатизован.\ да
\ модуль YANG? /------------+
'-----+-------' |
| нет |
v v
.-------------. +---------------+
+--> / Приложения с \ да | Регистрация |
| \ ограничениями?/---->| диапазона SID |<--------+
| '-----+-------' +------+--------+ |
| | нет | |
| v v |
| +---------------+ +---------------+ |
+----+ Обновление | | Выделение | |
| модуля YANG | | субблока SID |<---------+
+---------------+ +-------+-------+ |
| |
v |
+---------------+ +------+------+
| Генерация | | Переработка |
| файла .sid | | модуля YANG |
+-------+-------+ +-------------+
| ^
v |
.----------. да |
/ Работа \ ------------+
\ продолж.? /
'----+-----'
| нет
v
.-------------.
/ Публикация \ нет
\ RFC? /--------------+
'------+------' |
да | |
v v
+---------------+ +---------------+
| Регистрация | | Сторонняя |
| IANA | | регистрация |
+-------+-------+ +-------+-------+
| |
+------------------------+
v
[DONE]
Рисунок . Жизненный цикл SID.
На рисунке ниже кратко представлен процесс создания модуля YANG и файла .sid для него.
C.2. Обновление файла .sid
На рисунке ниже кратко представлен процесс обновления модуля YANG и связанного с ним файла .sid.
+--------------------+
o | Обновление модуля |
-+- -->| YANG, включённых и |
/ \ | импортируемых фалов|
+------+-------------+
|
v
.-------------.
/ Созданы новые \ да
\ элементы? /------+
'------+------' |
| нет v
| .-------------. +----------------+
| / Диапазон SID \ да | Выделение |
| \ исчерпан? /---->| дополнительного|
| '------+------' +-------+--------+
| | нет |
| +---------------------+
| |
| v
| +---------------+
| | Обновление |
| | файла .sid на |
| |основе прежнего|
| +-------+-------+
| |
| v
| .-------------. +---------------+
| / Доступен \ да | Регистрация |
| \ публично? /---->| модуля YANG |
| '------+------' +-------+-------+
| | нет |
+--------------+---------------------+
|
v
[DONE]
Рисунок . Обновление модуля YANG и файла .sid.
Приложение D. Сохранение файла .sid в файле данных экземпляра
В [RFC9195] определён формат данных экземпляра YANG (YANG instance data). Это, по сути, ведёт к инкапсуляции данных экземпляра в некую «оболочку» метаданных.
Если файл .sid нужно сохранить в файле данных экземпляра YANG, это можно сделать, встроив файл .sid как значение элемента content-data, как показано в шаблоне ниже (элементы второго уровня указаны в квадратных скобках).
{
"ietf-yang-instance-data:instance-data-set": {
"name": "<module-name>@<module-revision>.sid",
"description": ["<description>"],
"content-schema": {
"module": "ietf-sid-file@2024-06-17"
},
"content-data": { <замените этот объект>
"ietf-sid-file:sid-file" : {
"module-name": ...
}
}
}
}
Благодарности
Авторы благодарны Andy Bierman, Abhinav Somaraju, Peter van der Stok, Laurent Toutain и Randy Turner за помощь в создании этого документа и полезные комментарии в процессе рецензирования. Особая благодарность членам IESG, предоставившим очень полезные замечания в процессе обработки IESG, в частности, Benjamin Kaduk и Rob Wilton, а также Francesca Palombini (ответственный руководитель направления AD).
Участник работы
Andy Bierman YumaWorks 685 Cochran St. Suite #160 Simi Valley, CA 93065 United States of America Email: andy@yumaworks.comАдреса авторов
Michel Veillette (editor) Trilliant Networks Inc. 610 Rue du Luxembourg Granby Quebec J2J 2V2 Canada Phone: +1-450-375-0556 Email: michel.veillette@trilliant.com Alexander Pelov (editor) IMT Atlantique 2 rue de la Châtaigneraie 35510 Cesson-Sévigné Cedex France Email: alexander.pelov@imt-atlantique.fr Ivaylo Petrov (editor) Google Switzerland GmbH Brandschenkestrasse 110 CH-8002 Zurich Switzerland Email: ivaylopetrov@google.com Carsten Bormann Universität Bremen TZI Postfach 330440 D-28359 Bremen Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Michael Richardson Sandelman Software Works Canada Email: mcr+ietf@sandelman.caПеревод на русский язык
1Internet Engineering Task Force – комиссия по решению инженерных задач Internet.
2Internet Engineering Steering Group – комиссия по инженерным разработкам Internet.
3Network Configuration Protocol – протокол настройки сети.