Monitoring
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.
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.
There are really five types of filters available for retrieval operations:
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 |
Using Subtree Filters
The subtree filtering feature 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.
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.
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>
Using XPath Filters
The :xpath capability is fully supported, including the YANG extensions to this capability.
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.
Example Request:
xget //name
<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 Request:
xget //if:name
<?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 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>