Monitoring
There are several monitoring features available in the server.
Some are built-in and always available, and others need to be enabled with CLI parameters.
Some monitoring information is provided via special RPC operations and not stored in a database.
All standard NETCONF and RESTCONF monitoring data models are supported
Several YumaPro specific modules and augmentations are supported
Monitoring Operations
There are several builtin operations for retrieving YANG data from the server.
Operation |
Reference |
Notes |
|---|---|---|
Contains config=true from 'running' and all config='false' |
||
N/A |
Contains list entries from the specified datastore. |
|
Contains config=true from the specified datastore |
||
Contains all data from the specified NMDA datastore |
||
N/A |
Retrieve the High Availability (YP-HA) status for the server |
|
N/A |
Retrieve the module-tag mappings enabled on the server |
|
N/A |
Retrieve info about your NETCONF session |
|
Retrieve a YANG module |
||
N/A |
Retrieve the server version and build date |
|
N/A |
Retrieve the YANG library for the Schema Mount mountpoint |
|
N/A |
Retrieve server information for a support ticket. |
|
N/A |
Retrieve the YANG to SID mapping information for the server. |
Notes:
The <get> and <get-config> operations are fully supported for retrieving data from the <candidate> and <running> configuration databases.
The <get-config> operation is not supported for the <startup> configuration.
The <copy-config> operation is only supported copying the <running> configuration to the <startup> configuration.
NACM Filtering
If the NACM access control policy denies permission to read a particular node, then that node is silently skipped in the output. No error or warning messages will be generated.
Client applications should be prepared to receive XML subtrees that have been pruned by access control. The <data> element will always be present, so an empty <data/> element indicates that no data was returned, either because the <filter> did not match, or because access control pruned the requested nodes.
Filter Types
Type |
Description |
is_config() |
Choose the <get> operation for all objects, or <get-config> for just config=true objects |
is_default() |
Set the <with-defaults> parameter to 'trim' |
is_client_set() |
Set the <with-defaults> parameter to 'explicit' |
subtree filtering |
Use a subtree filter to retrieve portions of the <candidate> or <running> configurations. |
XPath filtering |
Use <filter type="xpath" select="expr"/> to retrieve portions of the <candidate> or <running> configurations. |
module-tag filtering |
Use the --module-tag parameter |
Built-in Monitoring Data
There are several top-level data node subtrees that are available. This section briefly describes this data.
For all examples in this section:
yangcli-pro display mode set to 'json'
yangcli-pro $$display-headers set to 'false'
/interfaces
The 'interfaces' subtree contains network interfaces information. This is the current RFC 8343 version.
Source: ietf-interfaces.yang
Enable: --module=ietf-interfaces
Example:
yangcli-pro command: sget /interfaces
Only 1 interface shown to save space
{
"ietf-interfaces:interfaces": {
"interface": [
{
"name":"eno1",
"description":"eno1",
"type":"iana-if-type:ethernetCsmacd",
"enabled":true,
"oper-status":"up",
"phys-address":"88:ae:dd:55:16:11",
"speed":"1000000000",
"statistics": {
"in-octets":"3062302397",
"in-multicast-pkts":"107550",
"in-discards":1541,
"in-errors":0,
"in-unknown-protos":0,
"out-octets":"361202085",
"out-discards":0,
"out-errors":0
}
}
]
}
}
/interfaces-state
The 'interfaces-state' subtree contains network interfaces information. This is the deprecated RFC 7223 version.
Source: ietf-interfaces.yang
Enable: --module=ietf-interfaces
Example:
yangcli-pro command: sget /interfaces-state
Only 1 interface shown to save space
{
"ietf-interfaces:interfaces-state": {
"interface": [
{
"name":"eno1",
"type":"iana-if-type:ethernetCsmacd",
"oper-status":"up",
"phys-address":"88:ae:dd:55:16:11",
"speed":"1000000000",
"statistics": {
"in-octets":"3063023796",
"in-multicast-pkts":"107910",
"in-discards":1546,
"in-errors":0,
"in-unknown-protos":0,
"out-octets":"361808885",
"out-discards":0,
"out-errors":0
}
}
]
}
}
/grpc-state
The 'grpc-state' subtree contains gRPC State Monitoring information.
Source: yumaworks-grpc-mon.yang
Enable: --with-grpc=true
Example: gRPC Monitoring Example
/modules-state
The 'modules-state' subtree contains YANG Library information. This is the deprecated RFC 7895 version. Since the 'module' list can be large, and the YANG library contents on the server do not change often, the '/modules-state/module-set-id' leaf should be used to help cache this information.
Source: ietf-yang-library.yang
Enable: Always enabled
Example:
yangcli-pro command: sget /modules-state
Only 1 module entry shown to save space
{
"ietf-yang-library:modules-state": {
"module-set-id":"8682",
"module": [
{
"name":"ietf-netconf",
"revision":"2011-06-01",
"namespace":"urn:ietf:params:xml:ns:netconf:base:1.0",
"feature": [
"candidate",
"confirmed-commit",
"rollback-on-error",
"validate",
"url",
"xpath"
],
"conformance-type":"implement",
"ietf-yang-library-augmentedby:augmented-by": [
"ietf-netconf-with-defaults",
"yuma-time-filter",
"yumaworks-system",
"yumaworks-templates"
]
}
]
}
}
/nacm
The 'nacm' subtree contains Access Control information.
This subtree is protected and only accessible if the user is a superuser or NACM rules are configured to allow access.
Source: ietf-netconf-acm.yang
Enable: Always enabled
Example:
yangcli-pro command: sget /nacm
{
"ietf-netconf-acm:nacm": {
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0
}
}
/netconf
The 'netconf' subtree contains NETCONF Notification information about the Event Streams available on the server.
Source: nc-notifications.yang
Enable: --with-notifications=true (default)
Example:
yangcli-pro command: sget /netconf
{
"nc-notifications:netconf": {
"streams": {
"stream": [
{
"name":"NETCONF",
"description":"default NETCONF event stream",
"replaySupport":true,
"replayLogCreationTime":"2026-03-13T18:51:25.101790Z"
}
]
}
}
}
/netconf-state
The 'netconf-state' subtree contains standard monitoring information about the NETCONF server.
Source: ietf-netconf-monitoring.yang
Enable: Always enabled
There are 6 sections within this subtree.
Section |
Description |
|---|---|
capabilities |
NETCONF capability statements supported by the server |
datastores |
state information about the datastores supported by the server |
schemas |
YANG module information. This subtree can be large. The '/modules-state' or '/yang-library' subtree should be used instead. |
sessions |
NETCONF session state information |
statistics |
NETCONF server statistics |
backup-files |
YumaPro specific backup startup-cfg file information |
Example:
yangcli-pro command: sget /netconf-state
/netconf-state/capabilities/capability leaf-list truncated to save space
/netconf-state/schemas/schema list truncated to save space
{
"yuma-netconf:data": {
"ietf-netconf-monitoring:netconf-state": {
"capabilities": {
"capability": [
"urn:ietf:params:netconf:base:1.0",
"urn:ietf:params:netconf:base:1.1",
"urn:ietf:params:netconf:capability:candidate:1.0",
"urn:ietf:params:netconf:capability:confirmed-commit:1.0",
"urn:ietf:params:netconf:capability:confirmed-commit:1.1",
"urn:ietf:params:netconf:capability:rollback-on-error:1.0",
"urn:ietf:params:netconf:capability:validate:1.0",
"urn:ietf:params:netconf:capability:validate:1.1",
"urn:ietf:params:netconf:capability:url:1.0?scheme=file",
"urn:ietf:params:netconf:capability:xpath:1.0",
"urn:ietf:params:netconf:capability:notification:1.0",
"urn:ietf:params:netconf:capability:interleave:1.0",
"urn:ietf:params:netconf:capability:partial-lock:1.0"
]
},
"datastores": {
"datastore": [
{
"name":"candidate",
"yuma-time-filter:last-modified":"2026-03-13T18:51:25Z"
},
{
"name":"running",
"yuma-time-filter:last-modified":"2026-03-13T18:51:25Z"
}
]
},
"schemas": {
"schema": [
{
"identifier":"iana-crypt-hash",
"version":"2014-08-06",
"format":"ietf-netconf-monitoring:yang",
"namespace":"urn:ietf:params:xml:ns:yang:iana-crypt-hash",
"location": [
"NETCONF"
],
"yumaworks-system:conformance":true,
"yumaworks-system:module-type":"module"
},
{
"identifier":"iana-if-type",
"version":"2017-01-19",
"format":"ietf-netconf-monitoring:yang",
"namespace":"urn:ietf:params:xml:ns:yang:iana-if-type",
"location": [
"NETCONF"
],
"yumaworks-system:conformance":true,
"yumaworks-system:module-type":"module"
}
]
},
"sessions": {
"session": [
{
"session-id":3,
"transport":"ietf-netconf-monitoring:netconf-ssh",
"username":"andy",
"source-host":"127.0.0.1",
"login-time":"2026-03-13T18:51:36Z",
"in-rpcs":16,
"in-bad-rpcs":0,
"out-rpc-errors":0,
"out-notifications":0
}
]
},
"statistics": {
"netconf-start-time":"2026-03-13T18:51:25Z",
"in-bad-hellos":0,
"in-sessions":1,
"dropped-sessions":0,
"in-rpcs":16,
"in-bad-rpcs":0,
"out-rpc-errors":0,
"out-notifications":0
},
"yumaworks-system:backup-files": {
"backup-file": [
{
"name":"test1.xml",
"backup-time":"2026-03-13T21:15:37Z"
}
]
}
}
}
}
/restconf-state
The 'restconf-state' subtree contains standard monitoring information about the RESTCONF server.
Source: ietf-restconf-monitoring.yang
Enable: --with-restconf=true
There are 2 sections within this subtree.
Section |
Description |
|---|---|
capabilities |
RESTCONF capability statements supported by the server |
streams |
RESTCONF event streams for RESTCONF Subscriptions |
Example:
yangcli-pro command: sget /restconf-state
{
"ietf-restconf-monitoring:restconf-state": {
"capabilities": {
"capability": [
"urn:ietf:params:restconf:capability:depth:1.0",
"urn:ietf:params:restconf:capability:with-defaults:1.0",
"urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=explicit",
"urn:ietf:params:restconf:capability:fields:1.0",
"urn:ietf:params:restconf:capability:replay:1.0",
"urn:ietf:params:restconf:capability:filter:1.0",
"urn:ietf:params:restconf:capability:yang-patch:1.0"
]
},
"streams": {
"stream": [
{
"name":"NETCONF",
"description":"default NETCONF event stream",
"replay-support":true,
"replay-log-creation-time":"2026-03-13T18:51:25Z",
"access": [
{
"encoding":"json",
"location":"http://localhost/restconf/streams/json-NETCONF"
},
{
"encoding":"xml",
"location":"http://localhost/restconf/streams/NETCONF"
}
]
},
{
"name":"RESTCONF",
"description":"default RESTCONF event stream",
"replay-support":true,
"replay-log-creation-time":"2026-03-13T18:51:25Z",
"access": [
{
"encoding":"xml",
"location":"http://localhost/restconf/stream"
}
]
}
]
}
}
}
/schema-mounts
The 'schema-mounts' subtree contains information about the standard Schema Mount mount points in use on the server.
Source: ietf-yang-schema-mount.yang
Enable: --with-schema-mount=true and --sm-config set
Example:
yangcli-pro command: sget /schema-mounts
{
"ietf-yang-schema-mount:schema-mounts": {
"mount-point": [
{
"module":"sm-test2",
"label":"mp1",
"config":true,
"inline": {
}
}
]
}
}
/server
The 'server' subtree contains the CLI and configuration file parameters in use by the server.
This subtree is protected and only accessible if the user is a superuser or NACM rules are configured to allow access.
Source: yumaworks-server.yang
Enable: --module='yumaworks-server'
Example:
yangcli-pro command: sget /server
{
"yumaworks-server:server": {
"log-level":"debug4",
"access-control":"off",
"bundle": [
"yang-push"
],
"module": [
"ietf-interfaces",
"iana-if-type"
],
"push-simop-patch-update":false,
"no-watcher":[null],
"with-yang-cbor":true,
"with-yuma-system":true,
"yang-sid-mode":"lsid"
}
}
/streams
The 'streams' subtree contains the Event Streams in use on the server.
Enable: --bundle=yang-push or --with-new-notifs=true
Example:
yangcli-pro command: sget /streams
{
"ietf-subscribed-notifications:streams": {
"stream": [
{
"name":"NETCONF",
"description":"default NETCONF event stream",
"replay-support":[null],
"replay-log-creation-time":"2026-03-13T21:40:24.792111Z",
"replay-log-aged-time":"2026-03-13T21:40:24.792111Z"
}
]
}
}
/system
The 'system' subtree contains system information about the host running the server.
Source: yuma-system.yang
Enable: --with-yuma-system=true
Example:
yangcli-pro command: sget /system
{
"yuma-system:system": {
"sysName":"localhost",
"sysCurrentDateTime":"2026-03-13T21:55:50Z",
"sysBootDateTime":"2026-03-13T21:40:24Z",
"sysLogLevel":"debug4",
"sysNetconfServerId":"netconfd-pro calico-integ-2026-03-13.11.33 (25.6.0)",
"sysNetconfStartupSource":"startup",
"sysNetconfStartupFilespec":"/home/andy/.yumapro/startup-cfg.xml",
"sysNetconfStartupTxidFilespec":"/home/andy/.yumapro/startup-cfg-txid.txt",
"sysNetconfServerCLI": {
"access-control":"off",
"bundle":"yang-push",
"config":"/home/andy/CONF/cbor.conf",
"log-level":"debug4",
"module":"yumaworks-server",
"module":"ietf-interfaces",
"module":"iana-if-type",
"module":"yumaworks-server",
"module":"sm-test2",
"push-simop-patch-update":"false",
"sm-config":"/home/andy/CONF/sm-mp1.json",
"no-watcher":[null],
"with-yang-cbor":"true",
"with-yuma-system":"true",
"yang-sid-mode":"lsid"
},
"uname": {
"sysname":"Linux",
"release":"6.8.0-101-generic",
"version":"#101~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Wed Feb 11 13:19:54 UTC ",
"machine":"x86_64",
"nodename":"andy-lenovo-pc2"
}
}
}
/system-capabilities
The 'system-capabilities' subtree contains standard information about the server capabilities from RFC 9196. It contains subscription capabilities for YANG Push.
Source: ietf-system-capabilities.yang
Enable: --with-yang-push2=true and --bundle=yang-push
Example:
yangcli-pro command: sget /system-capabilities
{
"ietf-system-capabilities:system-capabilities": {
"ietf-notification-capabilities:subscription-capabilities": {
"max-nodes-per-update":10000,
"periodic-notifications-supported":"config-changes state-changes",
"minimum-update-period":100,
"on-change-supported":"config-changes state-changes",
"minimum-dampening-period":100,
"supported-excluded-change-type": [
"all"
]
}
}
}
/yang-library
The 'yang-library' subtree contains YANG Library information. This is the current (NMDA) version from RFC 8525. Since the 'module' list can be large, and the YANG library contents on the server do not change often, the '/yang-library/content-id' leaf should be used to help cache this information.
Source: ietf-yang-library.yang
Enable: --with-nmda=true or --with-new-yanglib=true
Example:
yangcli-pro command: sget /yang-library
Only 1 module entry shown to save space
{
"yuma-netconf:data": {
"ietf-yang-library:yang-library": {
"module-set": [
{
"name":"modules",
"module": [
{
"name":"ietf-netconf",
"revision":"2011-06-01",
"namespace":"urn:ietf:params:xml:ns:netconf:base:1.0",
"feature": [
"candidate",
"confirmed-commit",
"rollback-on-error",
"validate",
"url",
"xpath"
],
"ietf-yang-library-augmentedby:augmented-by": [
"ietf-netconf-with-defaults",
"yuma-time-filter",
"yumaworks-system",
"yumaworks-templates"
]
}
]
}
],
"schema": [
{
"name":"schema1",
"module-set": [
"modules"
]
}
],
"datastore": [
{
"name":"ietf-datastores:candidate",
"schema":"schema1"
},
{
"name":"ietf-datastores:running",
"schema":"schema1"
}
],
"content-id":"8836"
}
}
}
/yang-sid-info
The 'yang-sid-info' subtree contains state information for Binary Push.
Source: yumaworks-yang-cbor.yang
Enable: --with-yang-cbor=true
Example:
yangcli-pro command: sget /yang-sid-info
{
"yumaworks-yang-cbor:yang-sid-info": {
"sid-set-id":"server1.8836",
"yang-sid-mode":"lsid",
"lsid-size":"lsid64",
"current-sid-max":"63230",
"current-sid-count":"3231"
}
}
Built-in Monitoring Metadata
Custom YANG Metadata can be used in database operations. There is also some built-in metadata for monitoring that is available in the server.
YANG Metadata is defined in RFC 7952 and supported in XML automatically.
The --with-yang-metadata CLI parameter must be set to 'true' (default) for JSON support
NETCONF fully supports all built-in YANG metadata using the following operations:
RESTCONF fully supports all built-in YANG metadata using the GET method for the following subtrees:
restconf/data/restconf/ds/{datastore}/
The metadata must be requested by the client in a retrieval operation.
Each metadata variable has its own RPC input parameter for NETCONF operation support:
Each metadata variable has its own query string parameter for RESTCONF retrieval support
with-defaults
The 'with-defaults' parameter is supported for Retrieving Default Values.
Variable: default
Source: RFC 6243
Module: ietf-netconf-with-defaults.yang
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults
JSON Prefix: ietf-netconf-with-defaults
Definition:
<xs:attribute name="default" type="xs:boolean" default="false"> <xs:annotation> <xs:documentation> This attribute indicates whether the data node represented by the XML element containing this attribute is considered by the server to be default data. If set to 'true' or '1', then the data node is default data. If 'false' or '0', then the data node is not default data. </xs:documentation> </xs:annotation> </xs:attribute>
The metadata variable 'wd:default' is returned for leaf and leaf-list data nodes if the parameter value 'report-all-tagged' is used.
Example: with-defaults Used to Retrieve a Default Container
The following YANG module 'testdef3.yang is used for the example in this section:
module testdef3 {
yang-version 1.1;
namespace "urn:yumaworks:params:xml:ns:yang:testdef3";
prefix "tdef3";
description
"
+--rw nptop
+--rw defleaf? uint32
+--rw defleaflist* uint32
+--rw npcon2
+--rw (defchoice)?
+--:(defleaf)
| +--rw defleaf? uint32
+--:(defleaflist)
+--rw defleaflist* uint32
";
revision 2026-04-04;
container nptop {
leaf defleaf {
type uint32;
default 42;
}
leaf-list defleaflist {
type uint32;
default "10";
default "20";
default "30";
}
leaf empty1 {
type empty;
}
container npcon2 {
choice defchoice {
default defleaflist;
leaf defleaf {
type uint32;
default 52;
}
leaf-list defleaflist {
type uint32;
default "11";
default "21";
}
}
}
}
}
In this example, the '/nptop' container does not exist, but it can be retrieved using the with-defaults parameter.
Example NETCONF <get> operation via yangcli-pro command:
sget /nptop with-defaults=report-all-tagged
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<nptop xmlns="urn:yumaworks:params:xml:ns:yang:testdef3"/>
</filter>
<with-defaults
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">report-all-tagged</with-defaults>
</get>
</rpc>
The server might send the following NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
xmlns:wda="urn:ietf:params:xml:ns:netconf:default:1.0"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T18:47:07Z" ncx:etag="31522"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nptop xmlns="urn:yumaworks:params:xml:ns:yang:testdef3">
<defleaf wda:default="true">42</defleaf>
<defleaflist wda:default="true">10</defleaflist>
<defleaflist wda:default="true">20</defleaflist>
<defleaflist wda:default="true">30</defleaflist>
<npcon2>
<defleaflist wda:default="true">11</defleaflist>
<defleaflist wda:default="true">21</defleaflist>
</npcon2>
</nptop>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl http://localhost/restconf/data/nptop?with-defaults=report-all-tagged
The server might send the following RESTCONF response:
{
"testdef3:nptop": {
"defleaf":42,
"@defleaf": {
"ietf-netconf-with-defaults:default":true
},
"defleaflist": [
10,
20,
30
],
"@defleaflist": [
{
"ietf-netconf-with-defaults:default":true
},
{
"ietf-netconf-with-defaults:default":true
},
{
"ietf-netconf-with-defaults:default":true
}
],
"npcon2": {
"defleaflist": [
11,
21
],
"@defleaflist": [
{
"ietf-netconf-with-defaults:default":true
},
{
"ietf-netconf-with-defaults:default":true
}
]
}
}
}
Refer to the With-defaults Examples for more details.
with-etag
The 'with-etag' parameter is supported for retrieving the last modification transaction ID saved when the configuration data node is created or modified.
The 'etag' attribute value is called the 'config-id' when it is for the root 'config' node.
The value is a 'uint64' value encoded as a string
The system transaction ID is incremented for every database transaction. The system transaction ID is usually saved across server reboots. The values may not appear consecutive to external clients, but they should always be increasing in value.
Variable: etag
Source: none
Module: yumaworks-attrs.yang
XML Namespace: http://yumaworks.com/ns/yumaworks-attrs
JSON Prefix: yumaworks-attrs
Definition:
md:annotation etag { type string; description "Contains the Entity Tag for the node containing this attribute."; }
The metadata variable 'ya:etag' is returned for container and list configuration data nodes.
Example: with-etag Used to Retrieve the /nacm Container
In this example the '/nacm/groups' container contains 1 group called 'admin'. The '/nacm/groups/group' subtree is created by a client somehow.
Example NETCONF <get-config> operation via yangcli-pro command:
sget-config /nacm source=running with-etag
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="10"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-etag xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</get-config>
</rpc>
The server may send the NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="10" xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T19:12:19Z" ncx:etag="31524"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm ya:etag="31524" xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups ya:etag="31524">
<group ya:etag="31524">
<name>admin</name>
<user-name>root</user-name>
<user-name>admin</user-name>
</group>
</groups>
</nacm>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl http://localhost/restconf/data/nacm?with-etag
The server might send the following RESTCONF response:
{
"ietf-netconf-acm:nacm": {
"@": {
"yumaworks-attrs:etag":"31524"
},
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"@": {
"yumaworks-attrs:etag":"31524"
},
"group": [
{
"@": {
"yumaworks-attrs:etag":"31524"
},
"name":"admin",
"user-name": [
"root",
"admin"
]
}
]
}
}
}
with-last-modified
The 'with-last-modified' parameter is supported for retrieving the last modification timestamp saved when the configuration data node is created or modified.
Variable: last-modified
Source: none
Module: yumaworks-attrs.yang
XML Namespace: http://yumaworks.com/ns/yumaworks-attrs
JSON Prefix: yumaworks-attrs
Definition:
md:annotation last-modified { type yang:date-and-time; description "Indicates the last-modified timestamp for the node containing this attribute."; }
The metadata variable 'ya:last-modified' is returned for container and list configuration data nodes.
Example: with-last-modified Used to Retrieve the /nacm Container
In this example the '/nacm/groups' container contains 1 group called 'admin'. The '/nacm/groups/group' subtree is created by a client somehow.
Example NETCONF <get-config> operation via yangcli-pro command:
sget-config /nacm source=running with-last-modified
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="11"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-last-modified xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</get-config>
</rpc>
The server may send the NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="11" xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T19:12:19Z" ncx:etag="31524"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm ya:last-modified="2026-05-01T19:12:19Z" xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups ya:last-modified="2026-05-01T19:12:19Z">
<group ya:last-modified="2026-05-01T19:12:19Z">
<name>admin</name>
<user-name>root</user-name>
<user-name>admin</user-name>
</group>
</groups>
</nacm>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl http://localhost/restconf/data/nacm?with-last-modified
The server might send the following RESTCONF response:
{
"ietf-netconf-acm:nacm": {
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z"
},
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z"
},
"group": [
{
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z"
},
"name":"admin",
"user-name": [
"root",
"admin"
]
}
]
}
}
}
with-origin
The 'with-origin' parameter is supported for retrieving the NMDA 'origin' attribute for a data node in the 'operational' datastore.
Variable: with-origin
Source: RFC 8527
Module: ietf-netconf-nmda.yang
XML Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-nmda
JSON Prefix: ietf-netconf-nmda
Attribute Source: RFC 8342
Attribute Module: ietf-origin.yang
Attribute XML Namespace: urn:ietf:params:xml:ns:yang:ietf-origin
Attribute JSON Prefix: ietf-origin
Definition:
leaf with-origin { when 'derived-from-or-self(../datastore, "ds:operational")'; if-feature "origin"; type empty; description "If this parameter is present, the server will return the 'origin' annotation for the nodes that have one."; }
The metadata variable 'or:origin' is returned for operational data nodes that have NMDA GET2 callbacks that provide this information.
with-owners
The 'with-owners' parameter is supported for retrieving the user-name representing the configuration owner, saved when the configuration data node is created or modified.
Variable: owner
Source: none
Module: yumaworks-attrs.yang
XML Namespace: http://yumaworks.com/ns/yumaworks-attrs
JSON Prefix: yumaworks-attrs
Definition:
md:annotation owner { type yt:NcxName; description "Contains the owner name for a data node."; }
The metadata variable 'ya:owner' is returned for configuration data nodes. Only the topmost affected node will retain an owner ID string.
Example: with-owners Used to Retrieve the /nacm Container
In this example the '/nacm/groups' container contains 1 group called 'admin'. The '/nacm/groups/group' subtree is created by a client somehow.
The 'with-etag' and 'with-last-modified' parameters are also used
Example NETCONF <get-config> operation via yangcli-pro command:
sget-config /nacm source=running with-owners with-etag with-last-modified
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="12"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-etag xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-last-modified xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-owners xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</get-config>
</rpc>
The server may send the NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="12" xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T19:12:19Z" ncx:etag="31524"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm ya:owner="andy" ya:last-modified="2026-05-01T19:12:19Z"
ya:etag="31524" xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups ya:last-modified="2026-05-01T19:12:19Z" ya:etag="31524">
<group ya:last-modified="2026-05-01T19:12:19Z" ya:etag="31524">
<name>admin</name>
<user-name>root</user-name>
<user-name>admin</user-name>
</group>
</groups>
</nacm>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl "http://localhost/restconf/data/nacm?with-owners&with-etag&with-last-modified"
The server might send the following RESTCONF response:
{
"ietf-netconf-acm:nacm": {
"@": {
"yuma-ncx:owner":"andy",
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z",
"yumaworks-attrs:etag":"31524"
},
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z",
"yumaworks-attrs:etag":"31524"
},
"group": [
{
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z",
"yumaworks-attrs:etag":"31524"
},
"name":"admin",
"user-name": [
"root",
"admin"
]
}
]
}
}
}
Example: All Parameters Used After /nacm Container Updated
In this example the '/nacm/groups' container contains 2 groups
1 called 'admin' created by user 'andy'
2 called 'guest' created by user 'netconf1'
Example NETCONF <get-config> operation via yangcli-pro command:
sget-config /nacm source=running with-owners with-etag with-last-modified
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-etag xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-last-modified xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-owners xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</get-config>
</rpc>
The server may send the NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4" xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T20:09:07Z" ncx:etag="31526"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm ya:owner="andy" ya:last-modified="2026-05-01T20:09:07Z"
ya:etag="31526" xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups ya:last-modified="2026-05-01T20:09:07Z" ya:etag="31526">
<group ya:last-modified="2026-05-01T19:12:19Z" ya:etag="31524">
<name>admin</name>
<user-name>root</user-name>
<user-name>admin</user-name>
</group>
<group ya:owner="netconf1" ya:last-modified="2026-05-01T20:09:07Z" ya:etag="31526">
<name>guest</name>
<user-name>guest1</user-name>
<user-name>guest2</user-name>
</group>
</groups>
</nacm>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl "http://localhost/restconf/data/nacm?with-owners&with-etag&with-last-modified"
The server might send the following RESTCONF response:
{
"ietf-netconf-acm:nacm": {
"@": {
"yuma-ncx:owner":"andy",
"yumaworks-attrs:last-modified":"2026-05-01T20:09:07Z",
"yumaworks-attrs:etag":"31526"
},
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T20:09:07Z",
"yumaworks-attrs:etag":"31526"
},
"group": [
{
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T19:12:19Z",
"yumaworks-attrs:etag":"31524"
},
"name":"admin",
"user-name": [
"root",
"admin"
]
},
{
"@": {
"yuma-ncx:owner":"netconf1",
"yumaworks-attrs:last-modified":"2026-05-01T20:09:07Z",
"yumaworks-attrs:etag":"31526"
},
"name":"guest",
"user-name": [
"guest1",
"guest2"
]
}
]
}
}
}
Example: All Parameters Used for /nacm Container After Reboot
In this example the '/nacm/groups' container contains 2 groups
1 called 'admin' created by user 'andy'
2 called 'guest' created by user 'netconf1'
The server has been rebooted:
The 'owner' attributes are preserved if --save-owners='true'
The 'etag' values should all be the same as the highest value used before the reboot.
The 'last-modified' values should all be set to the config boot timestamp
Example NETCONF <get-config> operation via yangcli-pro command:
sget-config /nacm source=running with-owners with-etag with-last-modified
The server may get the following NETCONF request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-etag xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-last-modified xmlns="http://yumaworks.com/ns/yumaworks-system"/>
<with-owners xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</get-config>
</rpc>
The server may send the NETCONF response:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns:ya="http://yumaworks.com/ns/yumaworks-attrs"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-05-01T20:17:34Z" ncx:etag="31526"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm ya:owner="andy" ya:last-modified="2026-05-01T20:17:34Z"
ya:etag="31526" xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups ya:last-modified="2026-05-01T20:17:34Z" ya:etag="31526">
<group ya:last-modified="2026-05-01T20:17:34Z" ya:etag="31526">
<name>admin</name>
<user-name>root</user-name>
<user-name>admin</user-name>
</group>
<group ya:owner="netconf1" ya:last-modified="2026-05-01T20:17:34Z" ya:etag="31526">
<name>guest</name>
<user-name>guest1</user-name>
<user-name>guest2</user-name>
</group>
</groups>
</nacm>
</data>
</rpc-reply>
Example RESTCONF GET method via curl command:
The client may send the following RESTCONF request:
curl "http://localhost/restconf/data/nacm?with-owners&with-etag&with-last-modified"
The server might send the following RESTCONF response:
{
"ietf-netconf-acm:nacm": {
"@": {
"yuma-ncx:owner":"andy",
"yumaworks-attrs:last-modified":"2026-05-01T20:17:34Z",
"yumaworks-attrs:etag":"31526"
},
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T20:17:34Z",
"yumaworks-attrs:etag":"31526"
},
"group": [
{
"@": {
"yumaworks-attrs:last-modified":"2026-05-01T20:17:34Z",
"yumaworks-attrs:etag":"31526"
},
"name":"admin",
"user-name": [
"root",
"admin"
]
},
{
"@": {
"yuma-ncx:owner":"netconf1",
"yumaworks-attrs:last-modified":"2026-05-01T20:17:34Z",
"yumaworks-attrs:etag":"31526"
},
"name":"guest",
"user-name": [
"guest1",
"guest2"
]
}
]
}
}
}
Using Subtree Filters
The subtree filtering feature defined in RFC 6241 is fully supported.
The order of nodes within the <filter> element is not relevant. Data returned in the <rpc-reply> should follow the same top-level order as the request, but this should not be relied on to always be the case.
Duplicate or overlapping subtrees within the request will be combined in the output, so the common ancestor nodes are not duplicated in the reply.
The
/filterssubtree from ietf-subscribed-notifications.yang is fully supported for storing reusable subtree and XPath filters in the server.
The following operations support a subtree filter parameter for selecting node-sets.
Operation |
Parameter |
Notes |
|---|---|---|
filter type='subtree' |
||
datastore-subtree-filter |
Datastore subscription |
|
stream-subtree-filter |
Event Stream subscription |
|
filter type='subtree' |
||
filter type='subtree' |
||
subtree-filter |
XML Namespaces
XML namespaces are optional to use:
If there is no namespace in affect for a filter component, or the 'NETCONF' namespace is in effect, the server will attempt to find any top-level data node which matches.
Namespaces within descendant nodes of the <filter> node children are inherited from their parent. If none is in effect, then the first matching child node for the current parent node will be used.
Invalid namespace errors for the <filter> element are suppressed in the server. An invalid namespace or unknown element is simply a 'no-match' condition.
For example, the following PDU would be valid, even though it is not technically valid XML:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="8">
<nc:get>
<nc:filter>
<nacm />
</nc:filter>
</nc:get>
</nc:rpc>
Note that there is no default namespace in effect for the <nacm> subtree. However, the server will accept this filter as if the ietf-netconf-acm.yang module namespace was properly declared.
The following request is shown with the proper XML namespace declaration.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="9" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
</get>
</rpc>
Content Match Filters
Subtree filters can select specific list entries using content match nodes. The following example would return the entire contents of the <interface> entry for 'eth0':
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="9">
<nc:get>
<nc:filter type="subtree">
<if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
<if:interface>
<if:name>eth0</if:name>
</if:interface>
</if:interfaces>
</nc:filter>
</nc:get>
</nc:rpc>
To retrieve only specific nodes (such as counters) from a single list entry, use select nodes for the desired counter(s), and include a content match node for each key leaf. A missing key leaf will match any entry for that key.
The following example request shows how just the <inBytes> and <outBytes> counters could be retrieved from the <interface> entry for 'eth0'.
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10">
<nc:get>
<nc:filter type="subtree">
<if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
<if:interface>
<if:name>eth0</if:name>
<if:counters>
<if:inBytes/>
<if:outBytes/>
</if:counters>
</if:interface>
</if:interfaces>
</nc:filter>
</nc:get>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10">
<nc:data>
<if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
<if:interface>
<if:name>eth0</if:name>
<if:counters>
<if:inBytes>290046042</if:inBytes>
<if:outBytes>112808406</if:outBytes>
</if:counters>
</if:interface>
</if:interfaces>
</nc:data>
</nc:rpc-reply>
Additional Subtree Filter Examples
A subtree filter is comprised of XML elements and their XML attributes. The following component types can appear in a subtree filter:
Namespace selection
Attribute match expressions
Containment nodes
Selection nodes
Content match nodes
Common scenarios and examples are described in RFC 6241. This section focuses on mixed combinations of selection and content match nodes, and how missing or non-matching nodes are handled.
Selection Nodes
An empty leaf node within a filter is a "selection node". It represents an explicit selection filter on the underlying data model. Any selection nodes within a set of sibling nodes cause the filter to select the specified subtree and suppress automatic selection of the entire sibling set in the underlying data model.
For filtering purposes, an empty leaf node can be declared with an empty tag (for example, "<foo/>") or with explicit start and end tags (for example, "<foo> </foo>"). Whitespace is ignored in this form.
Content Match Nodes
A leaf node that contains simple content is a "content match node". It selects some or all sibling nodes for filter output and represents an exact-match filter on the leaf node element content.
If all specified sibling content match nodes in a subtree filter expression are true, the filter output nodes are selected as follows:
Each content match node in the sibling set is included in the output.
Any containment nodes in the sibling set are processed, and included only if nested filter criteria are met.
Any selection nodes in the sibling set are included in the output.
Any sibling nodes of the selection node that are instance identifier components for a conceptual data structure (for example, list key leaf) MAY also be included in the output.
Otherwise, all nodes defined at this level in the underlying data model (and their subtrees, if any) are returned in the output.
If any sibling content match node test is false, no further filter processing is performed on that sibling set, and none of the sibling subtrees are selected by the filter, including the content match node.
Example Data Model
module subtree-test {
yang-version 1.1;
namespace "http://yumaworks.com/ns/subtree-test";
prefix "subtree-test";
revision "2020-03-03" {
description
"Initial test module for get2 callbacks";
}
container get2-state {
config false;
list port {
key name;
leaf name { type string; }
leaf type { type string; }
leaf nexttype { type string; }
leaf-list ll-type { type string; }
leaf-list ll-nexttype { type string; }
container aug-data {
leaf aug-type { type string; }
leaf aug-nexttype { type string; }
leaf-list aug-ll-type { type string; }
leaf-list aug-ll-nexttype { type string; }
}
}
}
}
Assume a <get> request on the top node returns the following:
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<type>some-type</type>
<ll-type>type1</ll-type>
<ll-type>type2</ll-type>
<aug-ll-type>aug-type1</aug-ll-type>
<aug-ll-type>aug-type2</aug-ll-type>
<aug-data>
<aug-type>sometype</aug-type>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
<aug-ll-nexttype>nexttype1</aug-ll-nexttype>
<aug-ll-nexttype>nexttype2</aug-ll-nexttype>
</aug-data>
</port>
<port>
<name>name2</name>
<nexttype>some-nexttype</nexttype>
<ll-nexttype>nexttype1</ll-nexttype>
<ll-nexttype>nexttype2</ll-nexttype>
<aug-ll-type>aug-type1</aug-ll-type>
<aug-ll-type>aug-type2</aug-ll-type>
<aug-data>
<aug-type>sometype</aug-type>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
<aug-ll-nexttype>nexttype1</aug-ll-nexttype>
<aug-ll-nexttype>nexttype2</aug-ll-nexttype>
</aug-data>
</port>
</get2-state>
</data>
</output>
Note that the two list entries have different child node values. This difference affects the output for the examples below.
Specific Selection Nodes in a Non-Specific Entry
The following request has no content match nodes; only selection nodes to select any entries that match "name" or "type" nodes.
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name/> <!--key-->
<type/> <!-- present only in list=name1 -->
</port>
</get2-state>
</filter>
</get>
The first list entry matches both "type" and "name", so it is returned with both nodes. The second list entry has no "type" node, but it still matches the "name" selection node, so it is also returned.
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<type>some-type</type>
</port>
<port>
<name>name2</name>
</port>
</get2-state>
</data>
</output>
Specific Selection Nodes without Key
The following request has selection nodes but no key specified:
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<nexttype/> <!-- present only in list=name2 -->
<ll-type/> <!-- present only in list=name1 -->
</port>
</get2-state>
</filter>
</get>
The first list entry (name1) matches the "ll-type" selection node. The second list entry (name2) matches the "nexttype" selection node. Both entries are returned.
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<ll-type>type1</ll-type>
<ll-type>type2</ll-type>
</port>
<port>
<name>name2</name>
<nexttype>some-nexttype</nexttype>
</port>
</get2-state>
</data>
</output>
Specific Selection Nodes from a Specific Entry
The following request includes a content match node for the key "name=name2" and a selection node "type". If the content match node does not match, the entry is excluded. If it matches and a selection node is present, that selection node is included if it exists.
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name2</name>
<type/>
</port>
</get2-state>
</filter>
</get>
The first list entry does not match the content match node and is pruned. The second entry matches the content match node. It does not contain the "type" node, so only the content match node is returned.
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name2</name>
</port>
</get2-state>
</data>
</output>
Specific Selection Nodes with Content Match Nodes
The following request has no content match node for a list key, so it targets any list entry. It does include a content match node for a leaf, so the server matches that content match node first and then applies selection nodes.
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name/>
<type>some-type</type>
<ll-type/>
</port>
</get2-state>
</filter>
</get>
The first list entry matches the "type" content match node, so it is returned with the "name" and "ll-type" selection nodes. The second list entry does not match the content match node and is pruned.
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<type>some-type</type>
<ll-type>type1</ll-type>
<ll-type>type2</ll-type>
</port>
</get2-state>
</data>
</output>
The following request produces the same output:
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name/>
<type>some-type</type>
<ll-type/>
<ll-nexttype/> <!-- not matching node -->
</port>
</get2-state>
</filter>
</get>
The "ll-nexttype" selection node is ignored because no matching node exists for that list entry.
Specific Content Match Nodes in a Non-Specific Entry
The following request finds any list entry with a specific content match node in a container. The server outputs all siblings of that content match node.
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<aug-data>
<aug-type>sometype</aug-type>
</aug-data>
</port>
</get2-state>
</filter>
</get>
Both list entries match the content match node, so both are returned with the sibling nodes under "aug-data".
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<aug-data>
<aug-type>sometype</aug-type>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
<aug-ll-nexttype>nexttype1</aug-ll-nexttype>
<aug-ll-nexttype>nexttype2</aug-ll-nexttype>
</aug-data>
</port>
<port>
<name>name2</name>
<aug-data>
<aug-type>sometype</aug-type>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
<aug-ll-nexttype>nexttype1</aug-ll-nexttype>
<aug-ll-nexttype>nexttype2</aug-ll-nexttype>
</aug-data>
</port>
</get2-state>
</data>
</output>
Specific Selection Nodes with Container Selection
The following request finds any list entry with a specific selection node. The server returns only the selected nodes.
<get>
<filter type="subtree">
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<type/>
<aug-data>
<aug-ll-type/>
</aug-data>
</port>
</get2-state>
</filter>
</get>
The first list entry matches both selection nodes and is returned with both. The second list entry matches the "aug-ll-type" selection node and is returned without the "type" node.
<output xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<get2-state xmlns="http://yumaworks.com/ns/subtree-test">
<port>
<name>name1</name>
<type>some-type</type>
<aug-data>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
</aug-data>
</port>
<port>
<name>name2</name>
<aug-data>
<aug-ll-type>type1</aug-ll-type>
<aug-ll-type>type2</aug-ll-type>
</aug-data>
</port>
</get2-state>
</data>
</output>
No extra nodes are returned under "aug-data" because the filter includes only selection nodes.
Using Regex Filters
A standard subtree filter content-match expression is an exact-match test. If the --with-regex-filter CLI parameter is set to 'true' (default) then regular expressions can also be used in content match expressions.
Regex Language Types
Both YANG and POSIX formats are supported for regular expression syntax. An expression prefix is used to identify the language.
r1: YANG pattern syntaxr2: POSIX (ocpattern) syntax
Regex Template
If enabled, then the server will check content-match expressions for the correct syntax:
prefix '(' expr ')'
If the string matches this template then it will be checked against data node values using the regex test, not an exact match.
Regex Example
Retrieve the 'interface' entries that have a name that starts with the string
eno
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>r1(eno.*)</name>
</interface>
</interfaces-state>
</filter>
</get>
</rpc>
The server might reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-09T21:13:16Z" ncx:etag="31046"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eno1</name>
<type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<oper-status>up</oper-status>
<phys-address>88:ae:dd:55:16:11</phys-address>
<speed>1000000000</speed>
<statistics>
<in-octets>19099920850</in-octets>
<in-unicast-pkts>18510467</in-unicast-pkts>
<in-multicast-pkts>1176410</in-multicast-pkts>
<in-discards>2203</in-discards>
<in-errors>0</in-errors>
<out-octets>3324564010</out-octets>
<out-unicast-pkts>10004507</out-unicast-pkts>
<out-discards>0</out-discards>
<out-errors>0</out-errors>
</statistics>
</interface>
</interfaces-state>
</data>
</rpc-reply>
Using XPath Filters
XPath is a powerful standard that can be used many ways with YANG data.
'must' and 'when' XPath expressions must have a 'boolean' result
'instance-identifier' restricted XPath expression must have a node-set result with at most one entry
'filter' XPath expression must have a node-set result
This section focuses on using XPath filters to select node-sets.
Full XPath Support
The XML Path Language (XPath) 1.0 is supported in netconfd-pro and YumaPro client programs (e.g. xget command) for selecting a subset of YANG data nodes from the server.
The NETCONF XPath Capability (:xpath) is fully supported.
The
/filterssubtree from ietf-subscribed-notifications.yang is fully supported for storing reusable subtree and XPath filters in the server.
The following operations support an XPath filter parameter for selecting node-sets.
Operation |
Parameter |
Notes |
|---|---|---|
filter type='xpath' |
||
datastore-xpath-filter |
Datastore subscription |
|
stream-xpath-filter |
Event Stream subscription |
|
filter type='xpath' |
||
list-test |
List node docroot |
|
filter type='xpath' |
||
xpath-filter |
XPath Usage
The XPath 2.0 rule for default XML namespace behavior is used, not XPath 1.0 rules, as specified by the YANG language. This means that any module with a node with the same local-name, in the same position in the schema tree, will match a missing XML prefix. This allows much simpler specification of XPath filters, but it may match more nodes than intended. Remember that any nodes added via an external YANG augment statement may have the same local-name, even though they are bound to a different XML namespace.
If the XPath expression does not return a node-set result, then the empty <data/> element will be returned in the <rpc-reply>.
If no nodes in the node-set result exist in the specified target database, then an empty <data/> element will be returned in the <rpc-reply>.
If a node in the result node-set matches a node in the target database, then it is included in the <rpc-reply>,
If a node selected for retrieval are contained within a YANG list node, then all the key leaf nodes for the specific list entry will be returned in the response.
The powerful '//' operator (equivalent to "descendant-or-self::node()") can be used to construct really simple XPath expressions.
The following example shows how a simple filter like '//name' will return nodes from all over the database, yet they can all be fully identified because the path from root is part of the response data.
Using the descendant-or-self Axis
XPath has a powerful feature that allows an entire subtree to be scanned
for objects with the same name. The double-slash operator // is defined
to represent this operator.
The string
//is short for/descendant-or-self::node()/.
Example: Retrieve all the data with a node called name
Example yangcli-pro request:
xget //name
Example Client Request:
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="43">
<nc:get>
<nc:filter type="xpath" select="//name"/>
</nc:get>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="43">
<nc:data>
<nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
<nacm:rules>
<nacm:data-rule>
<nacm:name>nacm-tree</nacm:name>
</nacm:data-rule>
<nacm:data-rule>
<nacm:name>itf-1</nacm:name>
</nacm:data-rule>
</nacm:rules>
</nacm:nacm>
<t:xpath.1 xmlns:t="http://netconfcentral.org/ns/test">
<t:name>barney</t:name>
</t:xpath.1>
<if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
<if:interface>
<if:name>lo</if:name>
</if:interface>
<if:interface>
<if:name>eth0</if:name>
</if:interface>
<if:interface>
<if:name>virbr0</if:name>
</if:interface>
<if:interface>
<if:name>pan0</if:name>
</if:interface>
</if:interfaces>
<ns:netconf-state xmlns:ns="urn:ietf:params:xml:ns:netconf:monitoring">
<ns:datastores>
<ns:datastore>
<ns:name>
<ns:candidate/>
</ns:name>
</ns:datastore>
<ns:datastore>
<ns:name>
<ns:running/>
</ns:name>
</ns:datastore>
<ns:datastore>
<ns:name>
<ns:startup/>
</ns:name>
</ns:datastore>
</ns:datastores>
</ns:netconf-state>
<manageEvent:netconf xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification">
<manageEvent:streams>
<manageEvent:stream>
<manageEvent:name>NETCONF</manageEvent:name>
</manageEvent:stream>
</manageEvent:streams>
</manageEvent:netconf>
</nc:data>
</nc:rpc-reply>
In order to refine the previous filter to select nodes from just one module, the use the XML prefix in the node identifier. The example below selects only the <name> nodes from the interfaces module.
Example yangcli-pro command:
xget //if:name
Example Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="44">
<nc:get>
<nc:filter type="xpath" xmlns:if="http://netconfcentral.org/ns/interfaces"
select="//if:name"/>
</nc:get>
</nc:rpc>
Example Reply:
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
message-id="44">
<nc:data>
<if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
<if:interface>
<if:name>lo</if:name>
</if:interface>
<if:interface>
<if:name>eth0</if:name>
</if:interface>
<if:interface>
<if:name>virbr0</if:name>
</if:interface>
<if:interface>
<if:name>pan0</if:name>
</if:interface>
</if:interfaces>
</nc:data>
</nc:rpc-reply>
Using XPath Predicate Expressions
Any valid node-set expression can be used in an XPath query.
The XPath result for the entire expression is a node-set
Predicates are used to remove instances from the node-set that do not match
Each predicate is a boolean expression. If 'true' the test node remains in the node-set. If 'false' that node is removed from the node-set.
The node just preceding the first predicate is the context node for all the predicates.
/foo/bar[name='test1'][type='type1']/leaf1
In this example the node
baris the context node for the 2 predicates that follow.In this example, all instances of
barare checked by the server. This is called the starting node-set.If an entry has a leaf called
namewith a value oftest1then it remains in the node-set.The node-set that remains is checked again. If an entry has a leaf named
typethat has a valuetype1then it remains in the node-set
For all nodes remaining in the node-set, if the
barentry has a child namedleaf1then this becomes the node in the node-set to replace its parent. Otherwise the parent is removed from the result node-set.The server returns the resulting
leaf1nodes and all its ancestor list, list key leafs, and containers.
Example: Retrieve only the interfaces with a 'speed' greater than zero
Example yangcli-pro request:
xget /interfaces-state/interface[speed>0]
Example Client Request:
Note that the '>' sign must be sent as a character entity because it is a special character in XML.
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="5"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="xpath" select="/interfaces-state/interface[speed>0]"/>
</get>
</rpc>
</rpc>
Example Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="5"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-12T21:22:59Z" ncx:etag="158"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>eno1</name>
<type
xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:ethernetCsmacd</type>
<oper-status>up</oper-status>
<phys-address>3c:7c:3f:1d:83:aa</phys-address>
<speed>1000000000</speed>
<statistics>
<in-octets>13648545351</in-octets>
<in-unicast-pkts>9525114</in-unicast-pkts>
<in-multicast-pkts>11786695</in-multicast-pkts>
<in-discards>0</in-discards>
<in-errors>0</in-errors>
<out-octets>2887923796</out-octets>
<out-unicast-pkts>3720106</out-unicast-pkts>
<out-discards>0</out-discards>
<out-errors>0</out-errors>
</statistics>
</interface>
</interfaces-state>
</data>
</rpc-reply>
Using XPath Functions
The XPath 1.0 function library is fully supported. There are restrictions for certain functions.
Refer to RFC 8407 Section 4.6.2 for details on YANG XPath usage.
Function calls can only appear in predicates or arguments to other function calls.
Example: Retrieve some inbound interface counters
Request only the statistics where the name starts with the string
in
Example yangcli-pro request:
xget /interfaces-state/interface/statistics/*[starts-with(local-name(.),'in')]
Example Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="xpath"
select="/interfaces-state/interface/statistics/*[starts-with(local-name(.),'in')]"/>
</get>
</rpc>
Example Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-12T21:22:59Z" ncx:etag="158"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
<interface>
<name>lo</name>
<statistics>
<in-octets>13231227</in-octets>
<in-unicast-pkts>105087</in-unicast-pkts>
<in-multicast-pkts>0</in-multicast-pkts>
<in-discards>0</in-discards>
<in-errors>0</in-errors>
</statistics>
</interface>
<interface>
<name>eno1</name>
<statistics>
<in-octets>13632758426</in-octets>
<in-unicast-pkts>9507673</in-unicast-pkts>
<in-multicast-pkts>11735283</in-multicast-pkts>
<in-discards>0</in-discards>
<in-errors>0</in-errors>
</statistics>
</interface>
<interface>
<name>virbr0</name>
<statistics>
<in-octets>0</in-octets>
<in-unicast-pkts>0</in-unicast-pkts>
<in-multicast-pkts>0</in-multicast-pkts>
<in-discards>0</in-discards>
<in-errors>0</in-errors>
</statistics>
</interface>
</interfaces-state>
</data>
</rpc-reply>
Using Depth Filters
The RESTCONF protocol defines a standard Depth Query Parameter to control the depth of subtrees returned in retrieval operations. This parameter is copied in IETF and YumaWorks YANG modules, and is also supported for the NETCONF protocol.
This filter can be used to reduce the amount of data returned by the server.
This parameter considers only data nodes when counting depth. The 'choice' and 'case' schema levels are ignored.
The nodes at the deepest depth requested are truncated
A container is returned as an empty element
A list is returned as an empty element in XML
A list is returned as an empty array in JSON or CBOR
A leaf or leaf-list is returned as normal
An anyxml or anydata is returned as normal
depth
The 'depth' parameter is supported in some NETCONF operations.
YANG Definition
leaf depth {
type union {
type enumeration {
enum unbounded {
description "All sub-resources will be returned.";
}
}
type uint16 {
range "1..max";
}
}
default unbounded;
description
"The 'depth' parameter from RESTCONF";
reference "RFC 8040.";
}
Operations
The following operations support the 'depth' parameter for limiting the depth of subtrees.
Operation |
Name |
Requires |
|---|---|---|
depth |
||
depth |
||
depth |
||
depth |
||
max-depth |
Starting Point
The depth starting point is the node used for 'depth=1'.
The depth parameter starting point depends on the target object used in the filter.
The starting point is the node that is considered depth=1
For the <get-bulk> operation this node is the 'list-target' object
For other operations the subtree or XPath filter used determines the starting point
Starting Point Examples
The following examples show how depth=1 is handled for different filters:
This filter is for the requested target node itself
No child nodes of the requested target node are returned
Example: Get only the data root
yangcli-pro Command:
sget / depth=1
Client NETCONF Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="7"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">1</depth>
</get>
</rpc>
Server NETCONF Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="7"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data></data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data?depth=1
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Last-Modified: Sun, 23 Nov 2025 18:01:25 GMT
ETag: 31064
Accept-Ranges: bytes
Content-Length: 29
Date: Sun, 23 Nov 2025 19:13:37 GMT
Server: lighttpd/1.4.63
{
"ietf-restconf:data": {}
}
Example: Get only the '/nacm' container
yangcli-pro Command:
sget /nacm depth=1
Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="8"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">1</depth>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
</get>
</rpc>
Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="8"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data/nacm?depth=1
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Accept-Ranges: bytes
Content-Length: 32
Date: Sun, 23 Nov 2025 19:15:14 GMT
Server: lighttpd/1.4.63
{
"ietf-netconf-acm:nacm": {}
}
Example: Get only the '/nacm/groups' container
yangcli-pro Command:
sget /nacm/groups depth=1
Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="9"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">1</depth>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups/>
</nacm>
</filter>
</get>
</rpc>
Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="9"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<groups/>
</nacm>
</data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data/nacm/groups?depth=1
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Last-Modified: Sun, 23 Nov 2025 18:01:25 GMT
ETag: 31064
Transfer-Encoding: chunked
Date: Sun, 23 Nov 2025 19:16:45 GMT
Server: lighttpd/1.4.63
{
"ietf-netconf-acm:groups": {}
}
Depth Parameter Examples
The '/nacm' container from ietf-netconf-acm.yang is used for this example.
The deepest node is 4 levels deep
Example: Get the '/nacm' container with depth=2
Level 2 example: '/nacm/groups'
Level 2 example: '/nacm/rule-list'
yangcli-pro Command:
sget /nacm depth=2
Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="10"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">2</depth>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
</get>
</rpc>
Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="10"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<denied-operations>0</denied-operations>
<denied-data-writes>0</denied-data-writes>
<denied-notifications>0</denied-notifications>
<groups/>
<rule-list/>
</nacm>
</data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data/nacm?depth=2
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Date: Sun, 23 Nov 2025 19:31:31 GMT
Server: lighttpd/1.4.63
{
"ietf-netconf-acm:nacm": {
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {},
"rule-list": []
}
}
Example: Get the '/nacm' container with depth=3
Level 3 example: '/nacm/groups/group'
Level 3 example: '/nacm/rule-list/rule'
yangcli-pro Command:
sget /nacm depth=3
Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="11"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">3</depth>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
</get>
</rpc>
Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="11"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<denied-operations>0</denied-operations>
<denied-data-writes>0</denied-data-writes>
<denied-notifications>0</denied-notifications>
<groups>
<group/>
</groups>
<rule-list>
<name>rulelist1</name>
<group>*</group>
<rule/>
</rule-list>
</nacm>
</data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data/nacm?depth=3
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Accept-Ranges: bytes
Content-Length: 248
Date: Sun, 23 Nov 2025 19:33:46 GMT
Server: lighttpd/1.4.63
{
"ietf-netconf-acm:nacm": {
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"group": []
},
"rule-list": [
{
"name":"rulelist1",
"group": [
"*"
],
"rule": []
}
]
}
}
Example: Get the '/nacm' container with depth=4
Level 4 example: '/nacm/groups/group/name'
Level 4 example: '/nacm/rule-list/rule/name'
yangcli-pro Command:
sget /nacm depth=4
Client Request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="12"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">4</depth>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
</get>
</rpc>
Server Reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="12"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-23T18:01:25Z" ncx:etag="31064"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<denied-operations>0</denied-operations>
<denied-data-writes>0</denied-data-writes>
<denied-notifications>0</denied-notifications>
<groups>
<group>
<name>G1</name>
<user-name>U1</user-name>
<user-name>U2</user-name>
</group>
<group>
<name>G2</name>
<user-name>U3</user-name>
<user-name>U4</user-name>
</group>
</groups>
<rule-list>
<name>rulelist1</name>
<group>*</group>
<rule>
<name>rule1</name>
<module-name>*</module-name>
<access-operations>*</access-operations>
<action>permit</action>
<comment>this is a permit all rule</comment>
</rule>
</rule-list>
</nacm>
</data>
</rpc-reply>
Client RESTCONF Request:
curl -i http://localhost/restconf/data/nacm?depth=4
Server RESTCONF Reply:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache
Pragma: no-cache
Accept-Ranges: bytes
Content-Length: 579
Date: Sun, 23 Nov 2025 19:34:48 GMT
Server: lighttpd/1.4.63
{
"ietf-netconf-acm:nacm": {
"denied-operations":0,
"denied-data-writes":0,
"denied-notifications":0,
"groups": {
"group": [
{
"name":"G1",
"user-name": [
"U1",
"U2"
]
},
{
"name":"G2",
"user-name": [
"U3",
"U4"
]
}
]
},
"rule-list": [
{
"name":"rulelist1",
"group": [
"*"
],
"rule": [
{
"name":"rule1",
"module-name":"*",
"access-operations":"*",
"action":"permit",
"comment":"this is a permit all rule"
}
]
}
]
}
}
Using Time Filters
The module yuma-time-filter.yang defines a timestamp mechanism to help reduce polling overhead for a client.
Timestamps are specified in 'date-and-time' format (from the ietf-yang-types.yang module).
The timestamp parameter 'if-modified-since' is added to the <get> and <get-config> operations.
The timestamp monitoring node 'last-modified' is added to the
/netconf-state/datastores/datastorelist.The XML attribute 'last-modified' is added to the <rpc-reply> element for replies to <get> and <get-config> operations.
The per-datastore last modified timestamp is for the entire datastore contents. If the 'if-modified-since' parameter is present in the <get> or <get-config> request, then the server will check the corresponding 'last-modified' timestamp.
If the 'last-modified' timestamp is more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is processed as normal.
If the 'last-modified' timestamp is not more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is not processed. Instead, an empty <data> element is returned. The 'last-modified' XML attribute in the <rpc-reply> will indicate the last modification timestamp for the datastore.
Example Request:
<?xml version="1.0" encoding="UTF-8"?>
<get-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<source>
<running/>
</source>
<if-modified-since
xmlns="http://netconfcentral.org/ns/yuma-time-filter">
2011-08-21T21:51:46Z</if-modified-since>
</get-config>
</rpc>
An empty reply is sent because datastore not modified since specified time:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
last-modified="2011-08-21T17:51:46Z"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data></data>
</rpc-reply>
if-modified-since
The 'if-modified-since' parameter is supported by the <get> and <get-config> operations.
The yuma-time-filter.yang module must be loaded for this parameter to be supported in the server.
The --with-yuma-time-filter parameter is used to enable this module (default true)
YANG Definition
leaf if-modified-since {
description
"If this parameter is present, then the server will
only process the retrieval request if the
corresponding 'last-modified' timestamp is
more recent than this timestamp. If so, then the
retrieval request is processed as normal.
If not, an empty <data> element will be returned.";
type yang:date-and-time;
Using Module Tag Filters
Module tags are defined in RFC 8819. They are used to map one or more module names to a user-defined tag string. The standard does not define any way to use module tags, but they are supported for filtering in retrieval operations.
Filters are combined into a conceptual 'AND' expression. All provided filters have to include a data node for it to be included in the result.
The YANG definition for the 'module-tag' parameter is defined in the yumaworks-app-common.yang module in the 'ModuleTagParm grouping:
grouping ModuleTagParm {
leaf-list module-tag {
type string {
length "1 .. 1023";
}
description
"Include only data nodes that match the module-tag.
Multiple module-tag parameters are combined as a
logical OR expression. Matching any tag value will
cause the data node to be included.
It is not an error to include an unknown module-tag.
Such tag values will simply be treated as a 'false'
match result, when evaluating the filter.
If any module-tag parameters are provided at all,
and there are no matches found, then no data will be
returned in the response.";
}
}
Defining Module Tag Mappings
The tag string has to be configured with the --module-tagmap parameter. This is done in the configuration file specified with the --config CLI parameter.
Example: Configure 3 modules to map to a tag called 'server-state'
netconfd-pro {
with-modtags true
module-tagmap ietf-netconf-monitoring@server-state
module-tagmap ietf-restconf-monitoring@server-state
module-tagmap ietf-subscribed-notifications@server-state
}
Retrieving the Module Tag Mappings
The yumaworks-system.yang module defines the <get-module-tags> operation. This can be used to retrieve all the configured module tag mappings.
Example:
The yangcli-pro command:
get-module-tags
The server may receive the following request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="10"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-module-tags xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>
The server may send the following reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="10"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">
<tag>server-state</tag>
<module>ietf-netconf-monitoring</module>
<module>ietf-restconf-monitoring</module>
<module>ietf-subscribed-notifications</module>
</module-tag>
</rpc-reply>
The yangcli-pro response might be displayed with the JSON --display-mode:
{
"yumaworks-system:module-tag": [
{
"tag":"server-state",
"module": [
"ietf-netconf-monitoring",
"ietf-restconf-monitoring",
"ietf-subscribed-notifications"
]
}
]
}
module-tag
The 'module-tag' parameter is supported by several NETCONF operations to select only modules that match the module tag.
leaf-list module-tag {
type string {
length "1 .. 1023";
}
description
"Include only data nodes that match the module-tag.
Multiple module-tag parameters are combined as a
logical OR expression. Matching any tag value will
cause the data node to be included.
It is not an error to include an unknown module-tag.
Such tag values will simply be treated as a 'false'
match result, when evaluating the filter.
If any module-tag parameters are provided at all,
and there are no matches found, then no data will be
returned in the response.";
}
Retrieving Data With a Module Tag Filter
Once a module tag mapping is defined, it can be used with the <get> and <get-config> operations.
Example: Retrieve the data associated with the 'server-state' tag. The 'depth' parameter is added so the response is not too big. It also shows how filters are combined by the server.
yangcli-pro Command:
sget module-tag=server-state / depth=3
The server may receive the following request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="14"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<depth xmlns="http://yumaworks.com/ns/yumaworks-system">3</depth>
<module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">server-state</module-tag>
</get>
</rpc>
The server may send the following reply:
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="14"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2026-03-03T21:04:59Z" ncx:etag="80"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<capabilities/>
<datastores/>
<schemas/>
<sessions/>
<statistics/>
</netconf-state>
<restconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
<capabilities/>
<streams/>
</restconf-state>
<streams xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream/>
</streams>
</data>
</rpc-reply>
The yangcli-pro response might be displayed with 'plain' mode:
data {
netconf-state {
capabilities {
}
datastores {
}
schemas {
}
sessions {
}
statistics {
}
}
restconf-state {
capabilities {
}
streams {
}
}
streams {
stream {
}
}
}
Retrieving Default Values
Normally, the server does not return default values in retrieval operations. The Default Node Handling section explains how the server treats default nodes.
Note
A YANG default is the value returned if no data node actually exists.
The definition of 'data node exists' varies and depends on the --default-style CLI parameter setting.
The server can be instructed to return default nodes using the 'with-defaults' parameter defined in RFC 6243.
with-defaults Parameter
The module ietf-netconf-with-defaults.yang defines the 'with-defaults' parameter. There are 4 enum values allowed:
report-all
report-all-tagged
trim
explicit
typedef with-defaults-mode {
description
"Possible modes to report default data.";
reference
"RFC 6243; Section 3.";
type enumeration {
enum report-all {
description
"All default data is reported.";
reference
"RFC 6243; Section 3.1";
}
enum report-all-tagged {
description
"All default data is reported.
Any nodes considered to be default data
will contain a 'default' XML attribute,
set to 'true' or '1'.";
reference
"RFC 6243; Section 3.4";
}
enum trim {
description
"Values are not reported if they contain the default.";
reference
"RFC 6243; Section 3.2";
}
enum explicit {
description
"Report values that contain the definition of
explicitly set data.";
reference
"RFC 6243; Section 3.3";
}
}
}
grouping with-defaults-parameters {
description
"Contains the <with-defaults> parameter for control
of defaults in NETCONF retrieval operations.";
leaf with-defaults {
description
"The explicit defaults processing mode requested.";
reference
"RFC 6243; Section 4.5.1";
type with-defaults-mode;
}
}
With-defaults Examples
The following examples show the differences between the different default
modes, using the default nodes from the /nacm subtree.
Plain Request
Server returns only non-default data nodes
The yangcli-pro command:
sget-config source=running /nacm
The client request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
</get-config>
</rpc>
The server response:
no data is returned since no NACM config has been set
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-11T21:14:00Z" ncx:etag="156"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data></data>
</rpc-reply>
With-defaults=trim
Server returns only non-default data nodes.
A data node is considered to be the default, even if the client set the node to its default vale.
This mode returns the same data as a 'plain' request.
The yangcli-pro command:
sget-config source=running /nacm with-defaults=trim
The client request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="5"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-defaults xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">trim</with-defaults>
</get-config>
</rpc>
The server response:
no data is returned since no NACM config has been set
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="5"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-11T21:14:00Z" ncx:etag="156"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data></data>
</rpc-reply>
With-defaults=explicit
Server returns only non-default data nodes.
A data node is considered to be the default only if no client has set the node.
A data node is returned even if it has a client-set value the same as the YANG default value.
This mode normally returns the same data as a 'plain' request. For this example, the leaf
/nacm/write-defaultis set to the YANG default valuedeny. Now this leaf and the parent container will exist as data nodes.
The yangcli-pro command:
sget-config source=running /nacm with-defaults=explicit
The client request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="12"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-defaults xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">explicit</with-defaults>
</get-config>
</rpc>
The server response:
the
/nacm/write-defaultleaf is returned.
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="12"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-11T21:28:23Z" ncx:etag="158"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<write-default>deny</write-default>
</nacm>
</data>
</rpc-reply>
With-defaults=report-all
Server returns all real data nodes and default data nodes.
The yangcli-pro command:
sget-config source=running /nacm with-defaults=report-all
The client request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="13"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-defaults xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">report-all</with-defaults>
</get-config>
</rpc>
The server response:
All default leafs within the
/nacmcontainer are returned.The default NP-container
/nacm/groupsis also returned
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="13"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-11T21:28:23Z" ncx:etag="158"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<enable-nacm>true</enable-nacm>
<read-default>permit</read-default>
<write-default>deny</write-default>
<exec-default>permit</exec-default>
<enable-external-groups>true</enable-external-groups>
<groups/>
</nacm>
</data>
</rpc-reply>
With-defaults=report-all-tagged
Server returns all real data nodes and default data nodes.
An XML attribute is also returned in each node that the server considers to be a default node.
The yangcli-pro command:
sget-config source=running /nacm with-defaults=report-all-tagged
The client request:
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="14"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<filter type="subtree">
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"/>
</filter>
<source>
<running/>
</source>
<with-defaults
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults">report-all-tagged</with-defaults>
</get-config>
</rpc>
The server response:
All default leafs within the
/nacmcontainer are returned.The default NP-container
/nacm/groupsis also returnedAll default nodes are tagged with the
wda:default="true"attribute
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="16"
xmlns:wda="urn:ietf:params:xml:ns:netconf:default:1.0"
xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
ncx:last-modified="2025-11-11T21:28:23Z" ncx:etag="158"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<enable-nacm wda:default="true">true</enable-nacm>
<read-default wda:default="true">permit</read-default>
<write-default wda:default="true">deny</write-default>
<exec-default wda:default="true">permit</exec-default>
<enable-external-groups wda:default="true">true</enable-external-groups>
<groups/>
</nacm>
</data>
</rpc-reply>