NETCONFSession

Represents a NETCONF session to a network device. NETCONFSession objects are created with Node::openNETCONFSession() method.

Each operation is executed as a separate request through the node’s effective NETCONF proxy agent, which connects to the device over SSH using the node’s SSH credentials. Consecutive calls may be served by different pooled NETCONF sessions on the proxy agent. Operations whose effect is bound to a single NETCONF session (lock, unlock, kill-session, close-session, and confirmed commit without persist) are therefore not supported.

All methods return null or false on failure; the reason is available in lastErrorMessage attribute. Calls to editConfig(), commit(), discardChanges(), and rpc() are recorded in the audit log (for rpc(), only the operation name is logged).

Instance attributes

lastErrorMessage: String

Text description of the last error, or empty string if the last operation completed successfully. For rpc() calls, contains text of rpc-error element if the device returned an error reply.

nodeId: int

ID of the node this session is connected to.

Instance methods

commit(): bool

Commit candidate configuration to the running configuration (NETCONF commit operation). Requires :candidate capability on the device.

Return

true on success, false on failure.

discardChanges(): bool

Revert candidate configuration to the current running configuration (NETCONF discard-changes operation). Requires :candidate capability on the device.

Return

true on success, false on failure.

editConfig(config, target, defaultOperation): bool

Modify configuration datastore (NETCONF edit-config operation).

Table 1. Parameters

config

String

Configuration to apply as XML document (content of the config element).

target

String

Target datastore: "running", "candidate", or "startup". Optional, "running" if omitted or null.

defaultOperation

String

Default operation for the configuration elements: "merge", "replace", or "none". Optional, device default (normally merge) is used if omitted or null.
Return

true on success, false if configuration document or arguments are invalid, communication failed, or the device returned an error.

session = $node.openNETCONFSession();
config = "<interfaces xmlns=\"urn:ietf:params:xml:ns:yang:ietf-interfaces\">" ..
         "<interface><name>eth1</name><description>Uplink to core</description></interface>" ..
         "</interfaces>";
if (session.editConfig(config, "candidate"))
{
   if (!session.commit())
      println("Commit failed: " .. session.lastErrorMessage);
}
else
{
   println("Edit failed: " .. session.lastErrorMessage);
}
get(filter, filterType): String

Retrieve running configuration and device state information (NETCONF get operation).

Table 2. Parameters

filter

String

Filter limiting the returned data: XML subtree filter or XPath expression, depending on filterType. Optional, all data is returned if omitted or null.

filterType

String

Filter type: "subtree" or "xpath". Optional, "subtree" if omitted or null. XPath filters require :xpath capability on the device.
Return

The data element of the reply (including the data tags) as XML string, or null on failure.

session = $node.openNETCONFSession();
data = session.get("<system xmlns=\"urn:ietf:params:xml:ns:yang:ietf-system\"><hostname/></system>");
if (data != null)
   println(data);
else
   println("NETCONF error: " .. session.lastErrorMessage);
getConfig(datastore, filter, filterType): String

Retrieve configuration from the given datastore (NETCONF get-config operation).

Table 3. Parameters

datastore

String

Source datastore: "running", "candidate", or "startup". Optional, "running" if omitted or null.

filter

String

Filter limiting the returned data: XML subtree filter or XPath expression, depending on filterType. Optional, full configuration is returned if omitted or null.

filterType

String

Filter type: "subtree" or "xpath". Optional, "subtree" if omitted or null.
Return

The data element of the reply (including the data tags) as XML string, or null on failure.

session = $node.openNETCONFSession();
interfaces = session.getConfig("running", "/if:interfaces/if:interface/if:name", "xpath");
rpc(content): String

Execute arbitrary NETCONF RPC. Use this method for operations not covered by other methods, such as vendor-specific RPCs.

Table 4. Parameters

content

String

RPC operation element as XML (without the rpc envelope).
Return

Full rpc-reply document as XML string, or null if the content is not valid XML, the operation is session-scoped (see above), or communication with the device failed. A reply containing rpc-error is still returned; check lastErrorMessage to detect it.

session = $node.openNETCONFSession();
reply = session.rpc("<get-schema xmlns=\"urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring\"><identifier>ietf-interfaces</identifier></get-schema>");
if ((reply == null) || (session.lastErrorMessage != ""))
   println("Error: " .. session.lastErrorMessage);
See also

Node