YANG Metadata Annotations for Junos Devices
SUMMARY Junos devices support YANG extensions that define metadata annotations, which you can use to perform specific operations on the Junos configuration.
Junos devices support YANG extensions to annotate instances of YANG data nodes with metadata. You can use the following extensions on supported devices:
-
junos-configuration-metadata—Juniper annotations that you can use to perform specific configuration operations. -
openconfig-metadata—Annotations defined by the OpenConfig working group.
YANG metadata annotations and their corresponding JSON and XML encoding are defined in
RFC 7952, Defining and Using Metadata with YANG. The
ietf-yang-metadata module defines the YANG extension
annotation.
YANG metadata annotations should not be confused with Junos configuration
annotations, which are comments that are included in the configuration, for example,
by using the annotate configuration mode command.
junos-configuration-metadata Module Overview
The Juniper Networks junos-configuration-metadata module defines
metadata annotations that enable you to perform specific operations on the Junos
configuration.
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.";
}
}
Devices that support the junos-configuration-metadata annotations
advertise the following capabilities in the NETCONF capabilities exchange:
<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>
Table 1 outlines the junos-configuration-metadata
annotations. The annotations use the
http://yang.juniper.net/junos/jcmd namespace URI and the
jcmd namespace prefix.
| Annotation | Value | Description |
|---|---|---|
active |
|
Deactivate the specified configuration statement. The statement remains in the configuration but does not affect the device's operation. |
true |
Activate the specified configuration statement. Use this annotation to activate a statement that was previously deactivated. |
|
comment |
string |
Add a comment with additional information about the specified configuration statement, or remove an existing comment by setting the value to an empty string (""). |
protect |
false |
Remove any previously applied |
true |
Prevent future modifications to the specified statement, until
such time that the |
Using junos-configuration-metadata Annotations in Configuration
Data
You can use the junos-configuration-metadata annotations in a
YANG-compliant NETCONF session to perform specific metadata operations on the
configuration. Supported operations include adding comments to the configuration,
deactivating or activating configuration hierarchies and statements, and protecting
configuration hierarchies and statements, as described in the following
sections:
- Add Comments in the Configuration
- Activate or Deactivate Configuration Statements
- Protect or Unprotect Configuration Statements
You can apply junos-configuration-metadata annotations on a
container (statement hierarchy), leaf-list, leaf statement, or a list item
(statement with an identifier). When you apply the annotations on leaf-list
statements, you can only apply them at the leaf-list level, not on individual
leaf-list entries.
You can use the YANG annotations in JSON or XML configuration data, as outlined in
Table 2. You can use the NETCONF <edit-config>
operation to load XML configuration data, and you can use the Junos XML protocol
<load-configuration> operation to load JSON or XML
configuration data on a device.
| Encoding | Syntax | Example |
|---|---|---|
|
JSON (metadata object) |
"module-name:annotation" : "value" |
|
|
XML (XML attributes) |
|
|
Add Comments in the Configuration
You can use the comment annotation to add comments to a
configuration statement. The following sections outline how to add a comment when
loading JSON or XML configuration data.
JSON
To add a comment when loading JSON configuration data, include the
junos-configuration-metadata:comment annotation in the
metadata object for that statement and specify the comment as a string. To
remove a comment, include an empty string ("").
The following example associates one comment with a hierarchy, another comment with a list entry that requires an identifier, and a third comment with an existing leaf statement.
<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
To add a comment when loading XML configuration data, include the
jcmd:comment annotation as an XML attribute in the opening
tag of that configuration element and specify the comment as a string. To remove
a comment, include an empty string ("").
The following example associates one comment with a hierarchy, another comment with a list entry that requires an identifier, and a third comment with a leaf statement.
<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>Activate or Deactivate Configuration Statements
You can use the active annotation to deactivate a configuration
statement or to activate a configuration statement that was previously deactivated.
To deactivate a statement, set active to false. To
activate a statement, set active to true.
The following sections outline how to deactivate and activate configuration statements in JSON and XML configuration data.
JSON
To deactivate or reactivate a configuration object in JSON, include the
"junos-configuration-metadata:active" : (false | true)
annotation in the metadata object for that statement.
<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>
For example, the following RPC deactivates the [edit protocols
isis] hierarchy, activates the apply-groups
leaf-list statement, and modifies the specified event policy to deactivate the
event-script action and reactivate the raise-trap action.
<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
To deactivate or reactivate a configuration object, include the
jcmd:active="false" or jcmd:active="true"
annotation, respectively, as an XML attribute in the opening tag of that
configuration element.
The following RPC deactivates the [edit protocols isis]
hierarchy, activates the apply-groups leaf-list statement, and
modifies the specified event policy to deactivate the event-script action and
reactivate the raise-trap action.
<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>Protect or Unprotect Configuration Statements
You can protect selected Junos configuration hierarchies and statements to prevent changes to those statements until such time that the protect attribute is removed.
The following sections outline how to protect or unprotect configuration statements in JSON and XML configuration data.
JSON
To protect or unprotect a configuration object in JSON, include the
"junos-configuration-metadata:protect" : (true | false)
annotation in the metadata object for that statement.
<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>
For example, the following RPC protects the [edit protocols
isis] hierarchy level, the apply-groups leaf-list
statement, and the host-name leaf statement, and it removes the
protect attribute for the specified event policy.
<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
To protect or unprotect a configuration object, include the
jcmd:protect="true" or
jcmd:protect="false" annotation, respectively, as an XML
attribute in the opening tag of that configuration element.
The following RPC protects the [edit protocols isis] hierarchy
level, the apply-groups leaf-list statement, and the
host-name leaf statement, and it removes the protect
attribute for the specified event policy.
<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 Module Overview
The
openconfig-metadata
YANG module includes metadata annotations defined by the OpenConfig
working group. The module defines the protobuf-metadata annotation,
which enables you to store metadata about the configuration directly within the
configuration for easy reference.
Junos devices support the openconfig-metadata:protobuf-metadata
annotation with the following constraints:
-
You can configure only one
protobuf-metadataannotation and only at the root level of the configuration hierarchy. -
You can only configure and view the annotation in JSON configuration data.
-
The annotation is of type binary, but you must encode the binary value in the base64 encoding scheme before loading the annotation on the device.
Junos devices support configuring the
openconfig-metadata:protobuf-metadata annotation by default.
However, to enable the device to emit the capability in the NETCONF capabilities
exchange and emit the annotation in the configuration data, you must configure the
device as follows:
-
Require the NETCONF server to advertise standard YANG modules, such as OpenConfig modules, in the capabilities exchange.
[edit] user@host# set system services netconf hello-message yang-module-capabilities advertise-standard-yang-modules
-
Configure the device to enforce YANG-compliant NETCONF sessions.
[edit] user@host# set system services netconf yang-compliant
-
(Optional) Unhide the OpenConfig schema, if you intend to view OpenConfig statements, including the annotation, in the CLI.
[edit] user@host# set system schema openconfig unhide
-
Commit the configuration.
[edit] user@host# commit
After you configure the device to advertise standard YANG modules in the NETCONF
capabilities exchange, devices that support openconfig-metadata
annotations advertise the following capability in the hello
message:
<capability>http://openconfig.net/yang/openconfig-metadata?module=openconfig-metadata&revision=2020-08-06</capability>
You use the gNMI set() operation to load the
openconfig-metadata:protobuf-metadata annotation as part of
your JSON configuration data.
{
"configuration" : {
"@" : {
"openconfig-metadata:protobuf-metadata": "dGhpcyBpcyB0ZXN0IGRhdGEK" // base64 encoded string per RFC 7951 encoding rules.
},
// configuration statements
}
}When you request JSON configuration data, as described in View Metadata Annotations in Configuration Data, the output displays the OpenConfig configuration, including the annotation, after the Junos configuration data. For example:
<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>View Metadata Annotations in Configuration Data
The Junos device emits YANG metadata annotations in the Junos configuration
within YANG-compliant NETCONF sessions. When you configure NETCONF sessions to
be YANG-compliant and retrieve the configuration using the
<get-config/> or
<get-configuration/> RPC, the device encodes the
annotations as per RFC 7952, Defining and Using Metadata with YANG.
To view the configuration with the YANG annotations encoded as per RFC 7952: