Internet Engineering Task Force (IETF) E. Voit
Request for Comments: 8650 R. Rahman
Category: Standards Track E. Nilsen-Nygaard
ISSN: 2070-1721 Cisco Systems
A. Clemm
Futurewei
A. Bierman
YumaWorks
November 2019
Dynamic Subscription to YANG Events and Datastores over RESTCONF
Динамическая подписка на события и хранилища YANG по протоколу RESTCONF
Аннотация
Документ задаёт привязку RESTCONF к свойству динамической подписки для уведомлений по подписке и YANG-Push.
Статус документа
Документ относится к категории Internet Standards Track.
Документ является результатом работы IETF1 и представляет согласованный взгляд сообщества IETF. Документ прошёл открытое обсуждение и был одобрен для публикации IESG2. Дополнительную информацию о стандартах Internet можно найти в разделе 2 RFC 7841.
Информацию о текущем статусе документа, ошибках и способах обратной связи можно найти по ссылке https://www.rfc-editor.org/info/rfc8650.
Авторские права
Авторские права (Copyright (c) 2019) принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.
К документу применимы права и ограничения, указанные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с упрощённой лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Simplified BSD License).
1. Введение
Механизмы для поддержки подписки на события и YANG-Push определены в [RFC8639]. Улучшения [RFC8639], обеспечивающие подписку на хранилища YANG и YANG-Push определены в [RFC8641]. Этот документ задаёт транспортную спецификацию для динамической подписки по протоколу RESTCONF [RFC8040]. Требования к механизмам заимстрованы из [RFC7923].
Потоковые уведомления, инкапсулирующие выталкиваемую информацию, организуются с помощью механизма, заданного в параграфе 6.3 [RFC8040].
2. Терминология
Ключевые слова необходимо (MUST), недопустимо (MUST NOT), требуется (REQUIRED), нужно (SHALL), не следует (SHALL NOT), следует (SHOULD), не нужно (SHOULD NOT), рекомендуется (RECOMMENDED), не рекомендуется (NOT RECOMMENDED), возможно (MAY), необязательно (OPTIONAL) в данном документе интерпретируются в соответствии с BCP 14 [RFC2119] [RFC8174] тогда и только тогда, когда они выделены шрифтом, как показано здесь.
Из [RFC8639] взяты термины dynamic subscription (динамическая подписка), event stream (поток событий), notification message (уведомление), publisher (издатель), receiver (получатель), subscriber (подписчик), subscription (подписка). Термин datastore (хранилище данных) определён в [RFC8342], а поток HTTP/2 сопоставляется с термином stream, определенным в разделе 2 [RFC7540].
3. Динамические подписки
В этом разделе описана организация и поддержика динамических подписок по протоколу RESTCONF [RFC8040]. Подписка на потоки событий в этом случае организуется через вызовы RPC, определённые в параграфе 2.4 [RFC8639], которые передаются через RESTCONF POST. Подписка на хранилища YANG реализуется через дополнения (augment) к [RFC8639], как описано в параграфе 2.4 [RFC8641].
Как описано в параграфе 6.3 [RFC8040], нужно выполнить операцию GET для указанного URI у издателя. Подписчики не могут заранее определить URI для подписки, поскольку URI будет существовать лишь после восприятия RPC establish-subscription. Поэтому POST для RPC establish-subscription применяется вместо GET для листа location, используемого в [RFC8040] для получения URI. Идентификатор URI для подписки определяется и передаётся как часть отклика на RPC establish-subscription и последующая операция GET для этого URI запускает процесс отправки уведомлений подписчику. Как указано в параграфе 2.4.1 [RFC8639], подписка не активируется до получения GET.
3.1. Транспортная связность
При отсутствии организованной ранее сессии RESTCONF для динамической подписки подписчик инициирует новую сессию RESTCONF. Как указано в параграфе 2.1 [RFC8040], подписчик должен организовать сессию HTTP с применением TLS [RFC8446] для защиты передаваемого содержимого.
Без привлечения дополнительных протоколов сессии HTTP не способны быстро обнаруживать потерю связности с издателем. Когда нужно быстро распознавать такую потерю, подписчику следует использовать TLS heartbeat [RFC6520] для отслеживания связности сессии HTTP. Потеря heartbeat должна приводить к разрыву всех связанных с подпиской сессий TCP между конечными точками. После этого подписчик может попытаться заново организовать подписку с использованием процедуры из параграфа 3.4.
3.2. Обнаружение
Подписчики могут узнать поддерживаемые сервером RESTCONF потоки событий, запросив контейнер streams из модуля ietf-subscribed-notifications.yang [RFC8639]. Поддержка контейнера streams из модуля ietf-restconf-monitoring.yang [RFC8040] не требуется. В случае использования заданной здесь привязки RESTCONF для доставки контейнера streams из модуля ietf-restconf-monitoring.yang (функция поддерживается) предполагается наличие всех содержащихся в нем потоков событий в контейнере streams из модуля ietf-restconf-monitoring.yang.
Подписчики могут узнать поддерживаемые сервером RESTCONF хранилища данных в соответствии с разделом 2 в [RFC8527].
3.3. RESTCONF RPC и коды состояния HTTP
Коды отклика HTTP, заданные в разделе 6 [RFC7231], будут указывать результат запроса RESTCONF RPC к издателю. Отклик HTTP с кодом 200 говорит об успешном выполнении RPC, заданных в [RFC8639] или [RFC8641].
Если у издателя возникает отказ при выполнении запроса RPC по одной или нескольким причинам, указанным в параграфе 2.4.6 [RFC8639] или Приложении A к [RFC8641], это указывается соответствующим кодом ошибки в отклике HTTP, как показано ниже. При возврате кода ошибки HTTP отклик RPC должен включать элемент <rpc-error> в соответствии с параграфом 7.1 [RFC8040], включающий указанные ниже параметры.
-
Узел error-type из application.
-
Узел error-tag, значением которого является строка, соответствующая связанному с ошибкой идентификатору. Значение error-tag соответствует идентификаторам ошибок из параграфа 2.4.6 в [RFC8639] для базовых ошибок (Таблица 1) или Приложения A.1 к [RFC8641] для ошибок, связанных с хранилищем YANG (Таблица 2).
-
Узел error-app-tag, значением которого является строка, соответствующая связанному с ошибкой идентификатору, как указано в параграфе 2.4.6 [RFC8639] для базовых ошибок или Приложении A.1 к [RFC8641] для ошибок подписки, связанных с хранилищами YANG. Применяемый тег зависит от вызова RPC, связанного с ошибкой (Таблица 3).
Таблица 1. Идентификаторы и теги базовых ошибок.
|
Идентификатор ошибки |
error-tag |
Код HTTP |
|---|---|---|
|
dscp-unavailable |
invalid-value |
400 |
|
encoding-unsupported |
invalid-value |
400 |
|
filter-unsupported |
invalid-value |
400 |
|
insufficient-resources |
resource-denied |
409 |
|
no-such-subscription |
invalid-value |
404 |
|
replay-unsupported |
operation-not-supported |
501 |
Таблица 2. Идентификаторы и теги ошибок связанных с хранилищем данных.
|
Идентификатор ошибки |
error-tag |
Код HTTP |
|---|---|---|
|
cant-include |
operation-not-supported |
501 |
|
datastore-not-subscribable |
invalid-value |
400 |
|
no-such-subscription-resync |
invalid-value |
404 |
|
on-change-unsupported |
operation-not-supported |
501 |
|
on-change-sync-unsupported |
operation-not-supported |
501 |
|
period-unsupported |
invalid-value |
400 |
|
update-too-big |
too-big |
400 |
|
sync-too-big |
too-big |
400 |
|
unchanging-selection |
operation-failed |
500 |
Таблица 3. Идентификаторы и теги ошибок RPC.
|
RPC |
Базовый идентификатор |
|---|---|
|
establish-subscription |
establish-subscription-error |
|
modify-subscription |
modify-subscription-error |
|
delete-subscription |
delete-subscription-error |
|
kill-subscription |
delete-subscription-error |
|
resync-subscription |
resync-subscription-error |
Каждый идентификатор ошибки будет помещаться как error-app-tag с использрванием кодирования JSON в форме <modulename>:<identityname>, например, ietf-subscribed-notifications:no-such-subscription.
При ошибке для запроса establish-subscription или modify-subscription имеется возможность включить узел error-info, который может содержать рекомендации для параметров, позволяющих предотвратить ошибку при последующем вызове RPC. В таблицах 4 и 5 показаны структуры yang-data, которые могут быть возвращены.
Таблица 4. Необязательные советы error-info для запроса establish-subscription.
|
Цель |
Возвращается в структуре yang-data |
|---|---|
|
Поток событий |
establish-subscription-stream-error-info |
|
Хранилище |
establish-subscription-datastore-error-info |
Таблица 5. Необязательные советы error-info для запроса modify-subscription.
|
Цель |
Возвращается в структуре yang-data |
|---|---|
|
Поток событий |
modify-subscription-stream-error-info |
|
Хранилище |
modify-subscription-datastore-error-info |
В yang-data внутри error-info не следует включать необязательный лист reason, поскольку он будет избыточным (все сведения уже присутствуют в error-app-tag).
Для <rpc-error> в результате ошибки при запроск delete-subscription, kill-subscription или resync-subscription не требуется включать error-info, поскольку subscription-id является единственным входным параметром RPC и давать какие-либо советы по входняс параметрам RPC не имеет смысла.
Отметим, что error-path [RFC8040] не требуется включать в элемент <rpc-error>, поскольку ошибки обычно связаны с выбором входных параметров RPC.
3.4. Поток вызовов для событий SSE
Поток вызовов для передаваемых сервером событий (Server-Sent Events или SSE) показан на рисунке 1. Логическими соединениями (a) и (b) могут быть соединения TCP или потоки HTTP/2 (при использовании HTTP/2 в одном соединении TCP может существовать несколько потоков HTTP/2). Запросы RPC, заданные в [RFC8639] или [RFC8641], передаются через соединение (a). Успешное выполнение establish-subscription будет приводить к отклику RPC с идентификатором подписки и URI с однозначным указанием местоположения подписки у издателя (b). Идентификатор URI задан листом uri в модели данных раздела 7.
HTTP GET передаётся через отдельное логическое соединение (b) с URI у издателя. Это указывает издателю, что нужно инициировать поток уведомлений, передаваемых в SSE [W3C-20150203], как отклик на GET. Не может быть передано несколько одновременных запросов GET для URI подписки и каждый запрос GET при обработке GET для того же URI должен отвергаться с кодом HTTP 409.
Как описано в параграфе 6.4 [RFC8040], серверам RESTCONF не следует передавать поля event и id в уведомлениях SSE.
Ниже указаны дополнительные требования к динамическим подпискам через SSE.
-
Издатель должен возвращать все уведомления о состоянии подписки в отдельном сообщении SSE, используемом подпиской, к которой относятся изменения статуса.
-
Для RPC подписки недопустимо использовать соединение, через которое в настоящее время передаются уведомления для этой подписки.
-
В дополнение к отклику на RPC modify-subscription через соединение (a), должно передаваться уведомление о смене состояния subscription-modified через соединение (b). Это позволит получателю точно знать, когда в потоке событий были приенены новые условия подписки (стрелка (c)).
-
В дополнение к требуемым правам доступа (например, NACM3), RPC modify-subscription, resync-subscription и delete-subscription следует разрешать лишь тому пользователю RESTCONF [RFC8040], который вызвал establish-subscription. Такое ограничение обычно служит для сохранения приватности пользователей, но могут применяться исключения для администраторов, которым может требоваться изменить или удалить подписки других пользователей.
-
RPC kill-subscription можно вызывать любому пользователю RESTCONF, имеющему права администратора.
+--------------+ +--------------+
| Пописчик | | Издатель |
| | | |
| Логическое | | Логическое |
| соединение | | соединение |
| (a) (b) | | (a) (b) |
+--------------+ +--------------+
| RESTCONF POST (RPC:establish-subscription) |
|--------------------------------------------->|
| HTTP 200 OK (ID,URI)|
|<---------------------------------------------|
| |HTTP GET (URI) |
| |--------------------------------------------->|
| | HTTP 200 OK|
| |<---------------------------------------------|
| | SSE (notif-message)|
| |<---------------------------------------------|
| RESTCONF POST (RPC:modify-subscription) | |
|--------------------------------------------->| |
| | HTTP 200 OK| |
|<---------------------------------------------| |
| | SSE (subscription-modified)|
| |<------------------------------------------(c)|
| | SSE (notif-message)|
| |<---------------------------------------------|
| RESTCONF POST (RPC:delete-subscription) | |
|--------------------------------------------->| |
| | HTTP 200 OK| |
|<---------------------------------------------| |
| | | |
| | | |
(a) (b) (a) (b)
Рисунок 1. Динамическая подписка с событиями SSE.
Издатель должен прерывать подписку в случае:
-
получения для неё RPC delete-subscription или kill-subscription;
-
потери TLS heartbeat.
Издатель может прервать подписку в любой момент, как указано в параграфе 1.3 [RFC8639].
4. Трактовка QoS
Обработка Qos для потока событий описана в параграфе 2.3 [RFC8639]. При использовании HTTP/2 издатель дополнительно должен соблюдать указанное ниже.
-
Принимать лист weighting [RFC8639] и копировать его в вес потока HTTP/2 (параграф 5.3 в [RFC7540]).
-
Принимать имеющиеся для подписки зависимости из листа dependency [RFC8639] и использовать поток HTTP/2 родительской подписки как зависимость потока HTTP/2 (параграф 5.3.1 в [RFC7540]) для зависимой подписки.
-
Сбросить (0) флаг исключительности (exclusive, параграф 5.3.1 в [RFC7540]).
Для динамических подписок с одним кодом дифференцированного обслуживания (Differentiated Services Code Point или DSCP) у конкретного издателя, подписчику рекомендуется передавать все запросы GET для URI в одной сессии HTTP/2 (если применяется HTTP/2). Для разных кодов DSCP подписчик не может использовать одну сессию HTTP/2.
5. Уведомления
Уведомления, доставляемые по протоколу RESTCONF, кодируются в соответствии с параграфом 6.4 [RFC8040].
6. Дерево YANG
Модуль YANG, заданный в разделе 7, имеет лист, дополняющий три узла из [RFC8639].
module: ietf-restconf-subscribed-notifications
augment /sn:establish-subscription/sn:output:
+--ro uri? inet:uri
augment /sn:subscriptions/sn:subscription:
+--ro uri? inet:uri
augment /sn:subscription-modified:
+--ro uri? inet:uri
7. Модуль YANG
Этот модуль ссылается на [RFC8639].
<CODE BEGINS>
file "ietf-restconf-subscribed-notifications@2019-11-17.yang"
module ietf-restconf-subscribed-notifications {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:"
+ "ietf-restconf-subscribed-notifications";
prefix rsn;
import ietf-subscribed-notifications {
prefix sn;
}
import ietf-inet-types {
prefix inet;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
Editor: Eric Voit
<mailto:evoit@cisco.com>
Editor: Alexander Clemm
<mailto:ludwig@clemm.org>
Editor: Reshad Rahman
<mailto:rrahman@cisco.com>";
description
"Задаёт RESTCONF как транспорт для уведомлений по подписке.
Авторские права (Copyright (c) 2019) принадлежат IETF Trust и
лицам, указанным как авторы. Все права защищены.
Распространение и применение модуля в исходной или двоичной
форме с изменениями или без таковых разрешено в соответствии с
лицензией Simplified BSD License, изложенной в параграфе 4.c
IETF Trust's Legal Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info).
Эта версия модуля YANG является частью RFC 8650, где правовые
аспекты приведены более полно.";
revision 2019-11-17 {
description
"Исходный выпуск";
reference
"RFC 8650: Dynamic Subscription to YANG Events and Datastores
over RESTCONF";
}
grouping uri {
description
"Описание URI, используемое неоднократно.";
leaf uri {
type inet:uri;
config false;
description
"Расположение связанного с подпиской URI у издателя.";
}
}
augment "/sn:establish-subscription/sn:output" {
description
"Позволяет использовать связанные с RESTCONF параметры
для откликов на запросы подписки.";
uses uri;
}
augment "/sn:subscriptions/sn:subscription" {
description
"Позволяет раскрывать связанные с RESTCONF параметры
для подписки.";
uses uri;
}
augment "/sn:subscription-modified" {
description
"Позволяет включать связанные с RESTCONF параметры в
уведомления об изменении подписки.";
uses uri;
}
}
<CODE ENDS>
8. Взаимодействие с IANA
Этот документ регистрирует URI в субреестре ns реестра IETF XML Registry [RFC3688].
URI: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications Registrant Contact: The IESG. XML: N/A; запрошенный URI является пространством имён XML.
Этот документ регистрирует модуль YANG в реестре YANG Module Names [RFC6020]:
Name: ietf-restconf-subscribed-notifications Namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications Prefix: rsn Reference: RFC 8650
9. Вопросы безопасности
Описанный в этом документе модуль YANG определяет схему данных, которая предназначения для доступа по протоколам сетевого управления, таким как NETCONF [RFC6241] или RESTCONF [RFC8040]. Нижним уровнем NETCONF является защищённый транспорт с обязательной поддержкой SSH4 [RFC6242]. Нижним уровнем RESTCONF является HTTPS с обязательной поддержкой TLS [RFC5246].
Модель управления доступом NETCONF (Network Configuration Access Control Model или NACM) [RFC8341] обеспечивает способы ограничения доступа отдельным пользователям NETCONF или RESTCONF заданным подмножеством всех доступных операций и содержимого NETCONF или RESTCONF.
Один из добавленных модулей YANG узлов данных может быть быть чувствительным или уязвимым в некоторых сетевых средах. Важно контролировать доступ к считыванию этого узла (например, через get, get-config, notification) в контейнере /subscriptions.
uri
Указывает место размещения включённых в подписку ресурсов у издателя. Права доступа должны быть установлены так, чтобы к ресурсу мог обращаться только тот пользователь RESTCONF [RFC8040], который вызвал establish-subscription.URI подписки зависит от реализации и шифруется с помощью TLS. Даже если атакующему удастся угадать URI, потребуется ещё имя пользователя RESTCONF [RFC8040] с соответствующей аутентификацией для получения доступа к подписке или её изменения. Рекомендуется применять труднопредсказуемые значения URI.
Вопросы прав доступа для RPC modify-subscription, resync-subscription, delete-subscription, kill-subscription рассмотрены в параграфе 3.4.
Если неисправный или скомпрометрированный подписчик RESTCONF может передавать большое число запросов establish-subscription, эти подписки накапливаются и могут отнять много ресурсов системы. В такой ситуации издатель может приостановить или прервать часть активных подписок этого подписчика RESTCONF для возврата ресурсов и обеспечения нормальной работы других подписчиков.
10. Литература
10.1. Нормативные документы
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., “The IETF XML Registry”, BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, <https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., “YANG – A Data Modeling Language for the Network Configuration Protocol (NETCONF)”, RFC 6020, DOI 10.17487/RFC6020, October 2010, <https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., “Network Configuration Protocol (NETCONF)”, RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., “Using the NETCONF Protocol over Secure Shell (SSH)”, RFC 6242, DOI 10.17487/RFC6242, June 2011, <https://www.rfc-editor.org/info/rfc6242>.
[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, “Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) Heartbeat Extension”, RFC 6520, DOI 10.17487/RFC6520, February 2012, <https://www.rfc-editor.org/info/rfc6520>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., “Hypertext Transfer Protocol Version 2 (HTTP/2)”, RFC 7540, DOI 10.17487/RFC7540, May 2015, <https://www.rfc-editor.org/info/rfc7540>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, “RESTCONF Protocol”, RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, “Network Configuration Access Control Model”, STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, “Network Management Datastore Architecture (NMDA)”, RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8446] Rescorla, E., “The Transport Layer Security (TLS) Protocol Version 1.3”, RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, “Subscription to YANG Notifications”, RFC 8639, DOI 10.17487/RFC8639, September 2019, <https://www.rfc-editor.org/info/rfc8639>.
[RFC8641] Clemm, A. and E. Voit, “Subscription to YANG Notifications for Datastore Updates”, RFC 8641, DOI 10.17487/RFC8641, September 2019, <https://www.rfc-editor.org/info/rfc8641>.
[W3C-20150203] Hickson, I., “Server-Sent Events”, W3C Recommendation, 3 February 2015, <https://www.w3.org/TR/2015/REC-eventsource-20150203/>. Latest version available at <https://www.w3.org/TR/eventsource/>.
10.2. Дополнительная литература
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”, RFC 7231, DOI 10.17487/RFC7231, June 2014, <https://www.rfc-editor.org/info/rfc7231>.
[RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, “Requirements for Subscription to YANG Datastores”, RFC 7923, DOI 10.17487/RFC7923, June 2016, <https://www.rfc-editor.org/info/rfc7923>.
[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>.
[RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. Zhang, “A YANG Data Model for the Virtual Router Redundancy Protocol (VRRP)”, RFC 8347, DOI 10.17487/RFC8347, March 2018, <https://www.rfc-editor.org/info/rfc8347>.
[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, “RESTCONF Extensions to Support the Network Management Datastore Architecture”, RFC 8527, DOI 10.17487/RFC8527, March 2019, <https://www.rfc-editor.org/info/rfc8527>.
[RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, “Dynamic Subscription to YANG Events and Datastores over NETCONF”, RFC 8640, DOI 10.17487/RFC8640, September 2019, <https://www.rfc-editor.org/info/rfc8640>.
[XPATH] Clark, J. and S. DeRose, “XML Path Language (XPath) Version 1.0”, W3C Recommendation, 16 November 1999, <http://www.w3.org/TR/1999/REC-xpath-19991116>. Latest version available at <https://www.w3.org/TR/ xpath/>.
Приложение A. Примеры
Это приложение не является нормативным. Для простоты сравнения здесь приведены функциональные примеры, использованные для NETCONF с XML в [RFC8640]. Заголовки HTTP/2 и HTTP/1.1 не приводятся, поскольку содержимое объектов в кодировке JSON идентично им.
Значения URI подписки в примерах являются лишь иллюстративными и не указывают предполагаемого использования, описанного в разделе 9. Значения DSCP приведены лишь для иллюстрации и используют десятичный формат из-за кодировки JSON [RFC7951].
A.1. Динамические подписки
A.1.1. Организация динамической подписки
На рисунке 2 приведены два успешных запроса RPC establish-subscription в соответствии с [RFC8639]. Первый запрос имеет идентификатор 22, второй – 23.
+------------+ +-----------+
| Подписчик | | Издатель |
+------------+ +-----------+
| |
|establish-subscription |
|------------------------------>| (a)
| HTTP 200 OK, id#22, URI#1 |
|<------------------------------| (b)
|GET (URI#1) |
|------------------------------>| (c)
| HTTP 200 OK,notif-mesg (id#22)|
|<------------------------------|
| |
| |
|establish-subscription |
|------------------------------>|
| HTTP 200 OK, id#23, URI#2|
|<------------------------------|
|GET (URI#2) |
|------------------------------>|
| |
| |
| notif-mesg (id#22)|
|<------------------------------|
| HTTP 200 OK,notif-mesg (id#23)|
|<------------------------------|
| |
Рисунок 2. Несколько подписок через RESTCONF/HTTP.
Ниже представлены примеры передаваемой информации для взаимодействий на рисунке 2.
POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription
{
"ietf-subscribed-notifications:input": {
"stream-xpath-filter": "/example-module:foo/",
"stream": "NETCONF",
"dscp": 10
}
}
Рисунок 3. Запрос establish-subscription (a).
Если издатель способен полностью выполнить запрос, он возвращает идентификатор организованной подписки и URI.
HTTP status code - 200
{
"ietf-subscribed-notifications:output": {
"id": 22,
"ietf-restconf-subscribed-notifications:uri":
"https://example.com/restconf/subscriptions/22"
}
}5
Рисунок 4. Запрос establish-subscription (b).
При получении отклика об успехе подписчик передаёт запрос GET для представленного URI, чтобы запустить поток уведомлений. При пулучении этого запроса издателем подписка переводится в активное состояние (c).
GET /restconf/subscriptions/22
Рисунок 5. GET после запроса establish-subscription6.
Если издатель не может полностью выполнить запрос или у подписчика нет прав на организацию подписки, издатель будет возвращать отклик об ошибке RPC (не показан на рисунке 2). Например, если указанное подписчиком значение dscp 10 (Рисунок 3), оказалось неприемлемым, издатель может возвратить отклик
HTTP status code - 400
{ "ietf-restconf:errors" : {
"error" : [
{
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag":
"ietf-subscribed-notifications:dscp-unavailable"
}
]
}
}
Рисунок 6. Отклик о неудаче establish-subscription.
Подписчик может применить полученные сведения при следующей попытке организовать подписку.
A.1.2. Изменение динамической подписки
Имеющуюся подписку можно изменить. На рисунке 7 показано согласование такого изменения путём обмена между подписчиком и издателем. Согласование включает запрос и отклик для неудачной попытки, затем – удачную подписку.
+------------+ +-----------+
| Подписчик | | Издатель |
+------------+ +-----------+
| |
| уведомление (id#23) |
|<-----------------------------|
| |
|modify-subscription (id#23) |
|----------------------------->| (d)
| Код HTTP 400 (с сосветом) |
|<-----------------------------| (e)
| |
|modify-subscription (id#23) |
|----------------------------->|
| HTTP 200 OK |
|<-----------------------------|
| |
| notif-mesg (id#23)|
|<-----------------------------|
| |
Рисунок 7. Модель взаимодействия при успешном изменении подписки.
Если подписка, изменяемая на рисунке 7 относится к хранилищу данных, как в [RFC8641], запрос на изменение (d) может иметь вид, показанный на рисунке 8. Предложенные изменения включают применение нового фильтра XPath (XML Path Language) и установку нового интервала периодической отправки.
POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription
{
"ietf-subscribed-notifications:input": {
"id": 23,
"ietf-yang-push:datastore-xpath-filter":
"/example-module:foo/example-module:bar",
"ietf-yang-push:periodic": {
"ietf-yang-push:period": 500
}
}
}
Рисунок 8. Запрос изменения подписки (c).
Если издатель может выполнить оба запроса, он будет возвращать положительный отклик для RPC. Если какое-либо изменение неприменимо, издатель передаёт отклик об ошибке RPC (e). Ниже представлен пример отклика об ошибке RPC (e), включающего совет, указывающий другой интервал, который может привести к успеху подписки.
HTTP status code - 400
{ "ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag": "ietf-yang-push:period-unsupported",
"error-info": {
"ietf-yang-push":
"modify-subscription-datastore-error-info": {
"period-hint": 3000
}
}
]
}
}
Рисунок 9. Отказ modify-subscription с советом (e).
A.1.3. Удаление динамической подписки
Ниже показано удаление подписки (поток событий или хранилище).
POST /restconf/operations
/ietf-subscribed-notifications:delete-subscription
{
"ietf-subscribed-notifications:input": {
"id": "22"
}
}7
Рисунок 10. Запрос delete-subscription.
Если издатель может выполнить запрос, он возвращает положительный отклик на запрос RPC.
Если издатель не может выполнить запрос, он передаёт элемент <rpc-error>, указывающий, что удаление не прошло. На рисунке 11 показан отклик для действительного идентификатора подписки, но созданного в другой транспортной сессии.
HTTP status code - 404
{
"ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag":
"ietf-subscribed-notifications:no-such-subscription"
]
}
}
Рисунок 11. Неудача delete-subscription.
A.2. Уведомления о статусе подписки
Издатель будет передавать уведомления о состоянии подписки в соответствии с определениями [RFC8639].
A.2.1. subscription-modified
Уведомление subscription-modified в кодировке JSON будет иметь вид
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-modified": {
"id": 39,
"uri": "https://example.com/restconf/subscriptions/39"
"stream-xpath-filter": "/example-module:foo",
"stream": {
"ietf-netconf-subscribed-notifications" : "NETCONF"
}
}
}
}8
Рисунок 12. Уведомление о состоянии подписки subscription-modified.
A.2.2. subscription-completed, subscription-resumed, replay-completed
Уведомление subscription-completed будет иметь вид
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-completed": {
"id": 39,
}
}
}
Рисунок 13. Уведомление subscription-completed в кодировке JSON.
Уведомления subscription-resumed и replay-complete практически идентичны, просто subscription-completed заменяется на subscription-resumed и replay-complete.
A.2.3. subscription-terminated и subscription-suspended
Уведомление subscription-terminated будет иметь вид
{
"ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-terminated": {
"id": 39,
"error-id": "suspension-timeout"
}
}
}
Рисунок 14. Уведомление о смене состояния subscription-terminated.
Уведомление subscription-suspended практически идентично subscription-terminated с соответствующей заменой.
A.3. Пример фильтра
В этом параграфе приведён пример, иллюстрирующий метод фильтрации содержимого записей о событиях. Пример основан уведомлении YANG vrrp-protocol-error-event, заданном в модуле ietf-vrrp.yang [RFC8347]. Записи о событиях, создаваемые издателем на основе этой спецификации могут иметь вид
data: {
data: "ietf-restconf:notification" : {
data: "eventTime" : "2018-09-14T08:22:33.44Z",
data: "ietf-vrrp:vrrp-protocol-error-event" : {
data: "protocol-error-reason" : "checksum-error"
data: }
data: }
data: }
Рисунок 15. RFC 8347 (VRRP) – пример уведомления.
Предположим, что подписчик хочет получать лишь записи о событиях, содержащие checksum-error в записи о событии протокола резервирования виртуального маршрутизатора (Virtual Router Redundancy Protocol или VRRP). Пусть издатель помещает такие записи о событиях в поток NETCONF. Для получения последовательнсти соответствующих записей подписчик может запросить применение фильтра XPath к потоку NETCONF. RPC establish-subscription для этого может иметь вид
POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription
{
"ietf-subscribed-notifications:input": {
"stream": "NETCONF",
"stream-xpath-filter":
"/ietf-vrrp:vrrp-protocol-error-event[
protocol-error-reason='checksum-error']/",
}
}
Рисунок 16. Указание ошибки при подписке через XPath.
Дополнительные примеры фильтров XPath приведены в [XPATH].
Предположим, что запрос establish-subscription (Рисунок 16) воспринят, а затем подписчик решил расширить подписку для охвата всех событий протокола VRRP (т. е., не только с checksum error). Подписчик может попытаться изменить подписку путём замены фильтра XPath фильтром ветвей, который будет передавать подписчику все события протокола VRRP. Такой вызов RPC modify-subscription может иметь вид
POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription
{
"ietf-subscribed-notifications:input": {
"stream": "NETCONF",
"stream-subtree-filter": {
"/ietf-vrrp:vrrp-protocol-error-event" : {}
}
}
}
Рисунок 17. Пример RPC modify-subscription.
Дополнительные фильтры ветвей можно найти в параграфе 6.4 [RFC6241].
Благодарности
Спасибо Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu, Robert Wilton за полезный вклад, комментарии и предложения.
Адреса авторов
Перевод на русский язык
Николай Малых
1Internet Engineering Task Force – комиссия по решению инженерных задач Internet.
2Internet Engineering Steering Group – комиссия по инженерным разработкам Internet.
3Network Configuration Access Control Model – модель управления доступом к настройке сети.
4Secure Shell – защищённая оболочка.
5В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6985. Прим. перев.
6В оригинале ошибочно указано POST. См. https://www.rfc-editor.org/errata/eid6379. Прим. перев.
7В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6985. Прим. перев.
8В оригинале этот фрагмент был указан с ошибкой. См. https://www.rfc-editor.org/errata/eid6369. Прим. перев.