Junos 设备的 YANG 元数据注释
总结 Junos 设备支持定义元数据注释的 YANG 扩展。
Junos 设备支持 YANG 扩展，以使用元数据注释 YANG 数据节点实例。您可以在支持的设备上使用以下扩展：
-
junos-configuration-metadata— 瞻博网络注释，可用于执行特定配置操作。 -
openconfig-metadata—由 OpenConfig 工作组定义的注释。
YANG 元数据注释及其相应的 JSON 和 XML 编码在 RFC 7952 中定义， 用于定义和使用 YANG 元数据。该 ietf-yang-metadata 模块定义 YANG 扩展 annotation。
YANG 元数据注释不应与 Junos 配置注释混淆，Junos 配置注释是配置中包含的评论，例如，使用 annotate 配置模式命令。
junos 配置元数据模块概述
瞻博网络 junos-configuration-metadata 模块定义元数据注释，使您能够在 Junos 配置上执行特定操作。
user@host> show system schema module junos-configuration-metadata output-directory /var/tmp
user@host> file show /var/tmp/junos-configuration-metadata.yang
/*
* junos-configuration-metadata.yang -- Defines annotations (RFC 7952) for
* Junos configuration metadata operations.
*
* Copyright (c) 2021, Juniper Networks, Inc.
* All rights reserved.
*/
module junos-configuration-metadata {
namespace "http://yang.juniper.net/junos/jcmd";
prefix "jcmd";
import ietf-yang-metadata {
prefix "md";
}
organization
"Juniper Networks, Inc.";
contact
"yang-support@juniper.net";
description
"This Yang module defines annotations (RFC 7951) for Junos configuration
metadata operations.";
revision 2021-09-01 {
description
"Initial version.";
}
md:annotation active {
type boolean;
description
"This annotation can be used in configuration XML/JSON to
deactivate/activate a configuration element. Specifying the value
'false' deactivates the configuration element. Specifying the
value 'true' activates the configuration element. When the
configuration element is deactivated and committed, the element
remains in the configuration, but the element does not affect the
functioning of the device.";
}
md:annotation protect {
type boolean;
description
"This annotation can be used in configuration XML/JSON to
protect/unprotect the configuration hierarchies and statements.
Specifying the value 'true' protects the configuration
hierarchy/statement. Specifying the value 'false' unprotects the
configuration hiearchy/statement. The protect operation
prevents changes to selected (protected) configuration hierarchies
and statements.";
}
md:annotation comment {
type string;
description
"This annotation must be used in configuration XML/JSON to
add comments to a configuration element. To remove the existing
comment, empty string has to be supplied as a value for this
annotation.";
}
}
支持注释的 junos-configuration-metadata 设备通告 NETCONF 功能交换中的以下功能：
<capability>http://yang.juniper.net/junos/jcmd?module=junos-configuration-metadata&revision=2021-09-01</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-yang-metadata?module=ietf-yang-metadata&revision=2016-08-05</capability>
表 1 概述了 junos-configuration-metadata 注释。注释使用 http://yang.juniper.net/junos/jcmd 名称空间 URI 和 jcmd 名称空间前缀。
| 注释 | 值 | 说明 |
|---|---|---|
active |
|
停用指定的配置语句。语句仍然保留在配置中，但不会影响设备的操作。 |
true |
激活指定的配置语句。使用此注释激活先前已停用的语句。 |
|
comment |
string |
添加有关指定配置语句的附加信息的备注，或将值设置为空字符串（“”）删除现有评论。 |
protect |
false |
从指定的配置语句中移除先前应用 |
true |
防止将来修改指定语句，直至 |
在配置数据中使用 junos-configuration-metadata 注释
您可以在符合 YANG 的 NETCONF 会话中使用 junos-configuration-metadata 注释对配置执行特定元数据操作。支持的操作包括向配置添加注释、停用或激活配置层次结构和语句，以及保护配置层次结构和语句，如以下部分所述：
您可以在容器（语句层次结构）、叶列表、叶语句或列表项目（使用标识符的语句）上应用 junos-configuration-metadata 注释。在叶列表语句上应用注释时，只能将其应用于叶列表级别，而不能应用于个别叶列表条目。
您可以使用 JSON 或 XML 配置数据中的 YANG 注释，如 表 2 中所述。您可以使用 NETCONF <edit-config> 操作加载 XML 配置数据，并且您可以使用 Junos XML 协议 <load-configuration> 操作在设备上加载 JSON 或 XML 配置数据。
| 编码 | 语法 | 示例 |
|---|---|---|
| JSON（元数据对象） |
“module-name：annotation” ： “value” |
|
| XML（XML 属性） |
|
|
在配置中添加注释
您可以使用 comment 注释在配置语句中添加注释。以下部分概述了如何在加载 JSON 或 XML 配置数据时添加评论。
Json
要在加载 JSON 配置数据时添加评论， junos-configuration-metadata:comment 请在元数据对象中包含该语句的注释，并将评论指定为字符串。要删除评论，请包含空字符串（“”）。
以下示例将一个评论与层次结构相关联，另一个评论与需要标识符的列表条目相关联，第三个评论与现有叶语句相关。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"protocols" : {
"ospf" : {
"@" : {
"junos-configuration-metadata:comment" : "/* OSPF comment */"
},
"area" : [
{
"name" : "0.0.0.0",
"interface" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* From jnpr1 \n to jnpr2 */"
},
"name" : "et-0/0/1.0",
"@hello-interval" : {
"junos-configuration-metadata:comment" : "# set by admin"
}
}
]
}
]
}
}
}
}
</configuration-json>
</load-configuration>
</rpc>
]]>]]>
Xml
要在加载 XML 配置数据时添加评论，请在该配置元素的开口标记中将 jcmd:comment 注释作为 XML 属性，并将评论指定为字符串。要删除评论，请包含空字符串（“”）。
以下示例将一个评论与层次结构相关联，另一个评论与需要标识符的列表条目相关联，第三个评论与叶语句相关。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<protocols>
<ospf xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="/* OSPF comment */">
<area>
<name>0.0.0.0</name>
<interface xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="/* From jnpr1 \n to jnpr2 */">
<name>et-0/0/1.0</name>
<hello-interval xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:comment="# set by admin">5</hello-interval>
</interface>
</area>
</ospf>
</protocols>
</configuration>
</config>
</edit-config>
</rpc>
激活或停用配置语句
您可以使用 active 注释停用配置语句或激活之前已停用的配置语句。要停用语句，请设置 active 为 false。要激活语句，请设置 active 为 true。
以下部分概述了如何在 JSON 和 XML 配置数据中停用和激活配置语句。
Json
要停用或重新激活 JSON 中的配置对象， "junos-configuration-metadata:active" : (false | true) 请在元数据对象中包含该语句的注释。
<configuration-json>
{
"configuration" : {
/* JSON objects for parent levels */
"@leaf-list-statement-name" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a leaf-list */",
"junos-configuration-metadata:active" : (false | true)
},
"level-or-container" : {
"@" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a hierarchy */",
"junos-configuration-metadata:active" : (false | true)
},
"object" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate an object with an identifier */",
"junos-configuration-metadata:active" : (false | true)
},
"name" : "identifier",
"@statement-name" : {
"junos-configuration-metadata:comment" : "/* activate or deactivate a statement */",
"junos-configuration-metadata:active" : (false | true)
}
}
]
}
/* closing braces for parent levels */
}
}
</configuration-json>
例如，以下 RPC 会停 [edit protocols isis] 用层次结构，激活 apply-groups 叶列表语句，并修改指定的事件策略以停用事件脚本操作并重新激活提升陷阱操作。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"@apply-groups" : {
"junos-configuration-metadata:active" : true
},
"protocols" : {
"isis" : {
"@" : {
"junos-configuration-metadata:active" : false
}
}
},
"event-options" : {
"policy" : [
{
"name" : "raise-trap-on-ospf-nbrdown",
"then" : {
"event-script" : [
{
"@" : {
"junos-configuration-metadata:active" : false
},
"name" : "ospf.xsl"
}
],
"@raise-trap" : {
"junos-configuration-metadata:active" : true
}
}
}
]
}
}
}
</configuration-json>
</load-configuration>
</rpc>
Xml
要停用或重新激活配置对象， jcmd:active="false" 请分别将或 jcmd:active="true" 注释作为该配置元素的开口标记中的 XML 属性。
以下 RPC 会 [edit protocols isis] 停用层次结构，激活 apply-groups 叶列表语句，并修改指定的事件策略以停用事件脚本操作并重新激活提升陷阱操作。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<apply-groups xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="true"/>
<protocols>
<isis xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="false"/>
</protocols>
<event-options>
<policy>
<name>raise-trap-on-ospf-nbrdown</name>
<then>
<event-script xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="false">
<name>ospf.xsl</name>
</event-script>
<raise-trap xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:active="true"/>
</then>
</policy>
</event-options>
</configuration>
</config>
</edit-config>
</rpc>
保护或未保护配置语句
您可以保护选定的 Junos 配置层次结构和语句，以防止更改这些语句，直至删除保护属性。
以下部分概述如何在 JSON 和 XML 配置数据中保护或取消保护配置语句。
Json
要在 JSON 中保护或卸下配置对象， "junos-configuration-metadata:protect" : (true | false) 请在元数据对象中包含该语句的注释。
<configuration-json>
{
"configuration" : {
/* JSON objects for parent hierarchies */
"@leaf-list-statement-name" : {
"junos-configuration-metadata:comment" : "/* protect a leaf-list */",
"junos-configuration-metadata:protect" : (false | true)
},
"hierarchy" : {
"@" : {
"junos-configuration-metadata:comment" : "/* protect a hierarchy */",
"junos-configuration-metadata:protect" : (false | true)
},
"object" : [
{
"@" : {
"junos-configuration-metadata:comment" : "/* protect an object with an identifier */",
"junos-configuration-metadata:protect" : (false | true)
},
"name" : "identifier",
"@statement-name" : {
"junos-configuration-metadata:comment" : "/* protect a statement */",
"junos-configuration-metadata:protect" : (false | true)
}
}
]
}
/* closing braces for parent hierarchies */
}
}
</configuration-json>
例如，以下 RPC 可保护 [edit protocols isis] 层次结构级别、 apply-groups 叶列表语句和 host-name 叶语句，并且移除指定事件策略的保护属性。
<rpc>
<load-configuration format="json">
<configuration-json>
{
"configuration" : {
"@apply-groups" : {
"junos-configuration-metadata:protect" : true
},
"system" : {
"@host-name" : {
"junos-configuration-metadata:protect" : true
}
},
"event-options" : {
"policy" : [
{
"@" : {
"junos-configuration-metadata:protect" : false
},
"name" : "raise-trap-on-ospf-nbrdown"
}
]
},
"protocols" : {
"isis" : {
"@" : {
"junos-configuration-metadata:protect" : true
}
}
}
}
}
</configuration-json>
</load-configuration>
</rpc>
Xml
要保护或取消保护配置对象， jcmd:protect="true" 请分别将或 jcmd:protect="false" 注释作为该配置元素的开口标记中的 XML 属性。
以下 RPC 可保护 [edit protocols isis] 层次结构级别、 apply-groups 叶列表语句和 host-name 叶语句，并且移除指定事件策略的保护属性。
<rpc>
<edit-config>
<target>
<candidate/>
</target>
<config>
<configuration>
<apply-groups xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
<system>
<host-name xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
</system>
<protocols>
<isis xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="true"/>
</protocols>
<event-options>
<policy xmlns:jcmd="http://yang.juniper.net/junos/jcmd" jcmd:protect="false">
<name>raise-trap-on-ospf-nbrdown</name>
</policy>
</event-options>
</configuration>
</config>
</edit-config>
</rpc>
openconfig-metadata 模块概述
openconfig-metadata YANG 模块包含由 OpenConfig 工作组定义的元数据注释。该模块定义protobuf-metadata了注释，使您能够将有关配置的元数据直接存储在配置中，以便于参考。
Junos 设备在以下限制下支持 openconfig-metadata:protobuf-metadata 注释：
-
您只能在配置层次结构的根层级配置一个注释和一个
protobuf-metadata注释。 -
您只能配置和查看 JSON 配置数据中的注释。
-
注释为二进制类型，但是在设备上加载注释之前，您必须在基本 64 编码方案中对二进制值进行编码。
Junos 设备支持默认配置 openconfig-metadata:protobuf-metadata 注释。但是，要使设备在 NETCONF 功能交换中发出功能并发出配置数据中的注释，您必须按以下内容配置设备：
-
要求 NETCONF 服务器在功能交换中通告标准 YANG 模块，例如 OpenConfig 模块。
[edit] user@host# set system services netconf hello-message yang-module-capabilities advertise-standard-yang-modules
-
配置设备以实施符合 YANG 的 NETCONF 会话。
[edit] user@host# set system services netconf yang-compliant
-
（可选）如果您打算在 CLI 中查看 OpenConfig 语句（包括注释），请解开 OpenConfig 方案。
[edit] user@host# set system schema openconfig unhide
-
提交配置。
[edit] user@host# commit
将设备配置为在 NETCONF 功能交换中通告标准 YANG 模块之后，支持 openconfig-metadata 注释的设备在消息中 hello 通告以下功能：
<capability>http://openconfig.net/yang/openconfig-metadata?module=openconfig-metadata&revision=2020-08-06</capability>
您可使用 gNMI set() 操作加载 openconfig-metadata:protobuf-metadata 注释作为 JSON 配置数据的一部分。
{
"configuration" : {
"@" : {
"openconfig-metadata:protobuf-metadata": "dGhpcyBpcyB0ZXN0IGRhdGEK" // base64 encoded string per RFC 7951 encoding rules.
},
// configuration statements
}
}
请求 JSON 配置数据时，如 “配置数据”中的 View Metadata 注释所述，输出将显示 Junos 配置数据之后的 OpenConfig 配置，包括注释。例如：
<rpc><get-configuration format="json"/></rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/22.3R1/junos">
{
"configuration" : {
"@" : {
"xmlns" : "http://xml.juniper.net/xnm/1.1/xnm",
"junos:changed-seconds" : "1658526284",
"junos:changed-localtime" : "2022-07-22 14:44:44 PDT"
},
"version" : "22.3R1-EVO",
...
},
"@" : {
"openconfig-metadata:protobuf-metadata" : "dGhpcyBpcyB0ZXN0IGRhdGEK"
},
"openconfig-interfaces:interfaces" : {
"interface" : [
{
"name" : "et-1/0/1",
"config" : {
"type" : "IF_ETHERNET",
"description" : "CE1"
}
}
]
}
}
</rpc-reply>
查看配置数据中的元数据注释
Junos 设备在符合 YANG 兼容 NETCONF 会话的 Junos 配置中发出 YANG 元数据注释。将 NETCONF 会话配置为符合 YANG 要求并使用 <get-config/> 或 <get-configuration/> RPC 检索配置时，设备会按照 RFC 7952 对注释进行编码，并 使用 YANG 元数据进行定义和使用。
要使用按照 RFC 7952 编码的 YANG 注释查看配置：