This section describes supported NETCONF operations to manipulate and query datastores. The client can send RPC messages for
these operations after establishing a session with the NETCONF agent. Basic usage explanations are given, and RFC 6242 can be referred to for thorough details about these operations.
<get-config>
This operation retrieves configuration data from a specified datastore. The supported parameters are <source> and <filter>. The <source> specifies the datastore being queried such as <running/>, which holds the currently active configuration. The <filter> specifies the portions of the specified datastore to retrieve.
The following are examples of <get-config> request and response messages.
-
Retrieve the entire
<System> subtree:<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter>
<System xmlns="http://cisco.com/ns/yang/cisco-nx-os-device"/>
</filter>
</get-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="101">
<data>
<System xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
...
</System>
</data>
</rpc-reply>
-
Retrieve a specific list item:
<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter>
<System xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<bgp-items>
<inst-items>
<dom-items>
<Dom-list>
<name>default</name>
</Dom-list>
</dom-items>
</inst-items>
</bgp-items>
</System>
</filter>
</get-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="102">
<data>
<System xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<bgp-items>
<inst-items>
<dom-items>
<Dom-list> <name>default</name>
...
<rtctrl-items>
<enforceFirstAs>enabled</enforceFirstAs>
<fibAccelerate>disabled</fibAccelerate>
<logNeighborChanges>enabled</logNeighborChanges>
<supprRt>enabled</supprRt>
</rtctrl-items>
<rtrId>1.2.3.4</rtrId>
</Dom-list>
</dom-items>
</inst-items>
</bgp-items>
</System>
</data>
</rpc-reply>
<edit-config>
This operation writes specified configuration to the target datastore.
The <target> parameter specifies the datastore being edited, such as <running/> or <candidate/>. The <running/> datastore
is manipulated to immediately change the switch config while the candidate datastore can be manipulated without impacting
the running datastore until its changes are committed. For more information, see the <commit> section.
The <config> parameter specifies the modeled data to be written to the target datastore. The intended model is specified by the “xmlns”
attribute. Any number of elements in the <config> subtree may contain an “operation” attribute. The operation of an element is inherited by its descendent elements until it’s
overridden by a new “operation” attribute. The supported operations are “merge”, “replace”, “create”, “delete”, and “remove”.
If the “operation” attribute is not specified, the “merge” operation is assumed as default; the default operation can be overridden
by the optional <default-operation> parameter, which could be “merge”, “replace” or “none”.
-
The “merge” operation is different from “create” in that no error is returned if the config data already exists.
-
The “remove” operation is different from “delete” in that no error is returned if the config data does not exist.
The following are examples of <edit-config> request and response messages.
-
Create a port-channel named "po5" with MTU 9216 and the description in the running configuration:
<rpc message-id="103" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<System
xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<intf-items>
<aggr-items>
<AggrIf-list xc:operation="create">
<id>po5</id>
<mtu>9216</mtu>
<descr>port-channel 5</descr>
</AggrIf-list>
</aggr-items>
</intf-items>
</System>
</config>
</edit-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="103">
<ok/>
</rpc-reply>
-
Replace all configurations of a port-channel with new configurations:
<rpc message-id="104" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<System
xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<intf-items>
<aggr-items>
<AggrIf-list xc:operation="replace">
<id>po5</id>
<mtu>1500</mtu>
<adminSt>down</adminSt>
</AggrIf-list>
</aggr-items>
</intf-items>
</System>
</config>
</edit-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="104">
<ok/>
</rpc-reply>
-
Delete a port-channel:
<rpc message-id="105" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<System xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<intf-items>
<aggr-items>
<AggrIf-list xc:operation="delete"> <id>po5</id>
</AggrIf-list>
</aggr-items>
</intf-items>
</System>
</config>
</edit-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="105">
<ok/>
</rpc-reply>
<copy-config>
This operation replaces the target configuration datastore with the contents of source configuration datastore. The parameters
for source datastore and target datastore are <source> and <target>, respectively.
The following are examples of <copy-config> request and response messages.
-
Copy from running configuration to startup configuration:
<rpc message-id="106" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<startup/>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="106">
<ok/>
</rpc-reply>
-
Copy from running configuration to candidate configuration:
<rpc message-id="107" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<candidate/>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="107">
<ok/>
</rpc-reply>
<lock>
The <lock> operation allows a client to lock the configuration datastore, preventing other clients from locking or modifying the datastore.
The lock that is held by the client is released with either the <unlock> operation or termination of a session. The <target> parameter is used to specify the datastore to be locked.
The following are examples of <lock> request and response messages.
-
A successful acquisition of a lock:
<rpc message-id="108" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="108">
<ok/>
</rpc-reply>
-
A failed attempt to acquire a lock already in use by another session:
<rpc message-id="109" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<candidate/>
</target>
</lock>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="109">
<rpc-error>
<error-type>protocol</error-type>
<error-tag>lock-denied</error-tag>
<error-severity>error</error-severity>
<error-message xml:lang="en">Lock failed, lock is already held</error-message>
<error-info>
<session-id>1553704357</session-id>
</error-info>
</rpc-error>
</rpc-reply>
<unlock>
The <unlock> operation releases a configuration lock, obtained with the <lock> operation. Only the same session that issued the <lock> operation can use the <unlock> operation. The <target> parameter is used to specify the datastore to be unlocked.
The following is an example of <unlock> request and response messages.
-
Unlock
<rpc message-id="110" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="110">
<ok/>
</rpc-reply>
<get>
The <get> operation retrieves running configuration and operational state data. The supported parameter is <filter>. The <filter> specifies the portions of the running configuration operational state data to retrieve.
The following is an example of <get> request and response messages.
-
Retrieve running configuration and operational state data of a list item:
<rpc message-id="111" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter>
<System
xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<bgp-items>
<inst-items>
<dom-items>
<Dom-list>
<name>default</name>
</Dom-list>
</dom-items>
</inst-items>
</bgp-items>
</System>
</filter>
</get>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="111">
<data>
<System
xmlns="http://cisco.com/ns/yang/cisco-nx-os-device">
<bgp-items>
<inst-items>
<dom-items>
<Dom-list>
<name>default</name>
<always>disabled</always>
<bestPathIntvl>300</bestPathIntvl>
<clusterId>120</clusterId>
<firstPeerUpTs>2020-04-20T16:19:03.784+00:00</firstPeerUpTs>
<holdIntvl>180</holdIntvl>
<id>1</id>
<kaIntvl>60</kaIntvl>
<mode>fabric</mode>
<numEstPeers>0</numEstPeers>
<numPeers>0</numPeers>
<numPeersPending>0</numPeersPending>
<operRtrId>1.2.3.4</operRtrId>
<operSt>up</operSt>
<pfxPeerTimeout>90</pfxPeerTimeout>
<pfxPeerWaitTime>90</pfxPeerWaitTime>
<reConnIntvl>60</reConnIntvl>
<rtrId>1.2.3.4</rtrId>
<vnid>0</vnid> ...
</Dom-list>
</dom-items>
</inst-items>
</bgp-items>
</System>
</data>
</rpc-reply>
<validate>
This operation validates the configuration contents of the candidate datastore. It is useful for validating the configuration
changes made on the candidate datastore before committing them to the running datastore. The <source> parameter supports <candidate/>.
The following is an example of <validate> request and response messages.
-
Validate the contents of the candidate datastore:
<rpc message-id="112" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="112">
<ok/>
</rpc-reply>
<commit>
This operation commits the candidate configuration to the running configuration. The operation without any parameter is considered
final and cannot be reverted.
If <commit> is issued with the <confirmed/> parameter, it is considered a confirmed commit, and commit is finalized only if it is followed by another <commit> operation
without the <confirmed/> parameter. That is, the confirming commit. The confirmed commit allows two parameters: <confirm-timeout> and <persist>. The
<confirm-timeout> is the period in seconds before the confirmed commit is reverted, restoring the running configuration to its state before
the confirmed commit was issued, unless the confirming commit is issued before, or the timeout is reset by another confirmed
commit. If the <confirm-timeout> is not specified, the default timeout is 600 seconds. Also, the confirmed commit is reverted if the session is terminated.
The <persist> parameter makes the confirmed commit to persist even if the session is terminated. The value of the <persist> parameter is used to identify the confirmed commit from any session and must be used as the value of the <persist-id> parameter of subsequent confirmed commit or confirming commit.
The following are examples of <commit> request and response messages.
-
Commit the contents of the candidate datastore:
<rpc message-id="113" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit/>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="113">
<ok/>
</rpc-reply>
-
Confirmed commit with the timeout:
<rpc message-id="114" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<confirm-timeout>120</confirm-timeout>
</commit>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="114">
<ok/>
</rpc-reply>
-
Start a persistent confirmed commit and then confirm the persistent confirmed commit:
<rpc message-id="115" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<persist>ID1234</persist>
</commit>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="115">
<ok/>
</rpc-reply>
<!-- confirm the persistent confirmed-commit, from the same session or another session -->
<rpc message-id="116" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<persist-id>ID1234</persist-id>
</commit>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="116">
<ok/>
</rpc-reply>
<cancel-commit>
This operation cancels an ongoing confirmed commit. If a confirmed commit from a different session needs to be canceled, the
<persist-id> parameter must be used with the same value that was given in the <persist> parameter of the confirmed commit.
-
Cancel the confirmed commit from the same sessions:
<rpc message-id="117" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<cancel-commit/>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="117">
<ok/>
</rpc-reply>
<discard-changes>
This operation discards any uncommitted changes that are made on the candidate configuration by resetting back to the content
of the running configuration. No parameter is required.
The following is an example of <discard-changes> request and response messages.
-
Discard the changes made on the candidate datastore:
<rpc message-id="118" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<discard-changes/>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="118">
<ok/>
</rpc-reply>
Feedback