manager – High-level API

This module is a thin layer of abstraction around the library. It exposes all core functionality.

Module data

These attributes control what capabilties are exchanged with the NETCONF server and what operations are available through the Manager API.

ncclient.manager.OPERATIONS
Dictionary of method names and corresponding RPC subclasses. It is used to lookup operations, e.g. “get_config” is mapped to GetConfig. It is thus possible to add additional operations to the Manager API.
ncclient.manager.CAPABILITIES
A list of URI’s representing the client’s capabilities. This is used during the initial capability exchange. Modify this if you need to announce some capability not already included.

Factory functions

A Manager instance is created using a factory function.

ncclient.manager.connect_ssh(host[, port=830, timeout=None, unknown_host_cb=default_unknown_host_cb, username=None, password, key_filename=None, allow_agent=True, look_for_keys=True])

Initializes a NETCONF session over SSH, and creates a connected Manager instance. host must be specified, all the other arguments are optional and depend on the kind of host key verification and user authentication you want to complete.

For the purpose of host key verification, on -NIX systems a user’s ~/.ssh/known_hosts file is automatically considered. The unknown_host_cb argument specifies a callback that will be invoked when the server’s host key cannot be verified. See default_unknown_host_cb() for function signature.

First, publickey authentication is attempted. If a specific key_filename is specified, it will be loaded and authentication attempted using it. If allow_agent is True and an SSH agent is running, the keys provided by the agent will be tried. If look_for_keys is True, keys in the ~/.ssh/id_rsa and ~.ssh/id_dsa will be tried. In case an encrypted key file is encountered, the password argument will be used as a decryption passphrase.

If publickey authentication fails and the password argument has been supplied, password / keyboard-interactive SSH authentication will be attempted.

Parameters:
  • host (string) – hostname or address on which to connect
  • port (int) – port on which to connect
  • timeout (int) – timeout for socket connect
  • unknown_host_cb (function) – optional; callback that is invoked when host key verification fails
  • username (string) – username to authenticate with, if not specified the username of the logged-in user is used
  • password (string) – password for password authentication or passphrase for decrypting private key files
  • key_filename (string) – location of a private key file on the file system
  • allow_agent (bool) – whether to try connecting to SSH agent for keys
  • look_for_keys (bool) – whether to look in usual locations for keys
Raises:

SSHUnknownHostError

Raises:

AuthenticationError

Return type:

Manager

ncclient.manager.connect
Same as connect_ssh(), since SSH is the default (and currently, the only) transport.

Manager

Exposes an API for RPC operations as method calls. The return type of these methods depends on whether we are is in asynchronous or synchronous mode.

In synchronous mode replies are awaited and the corresponding RPCReply object is returned. Depending on the exception raising mode, an rpc-error in the reply may be raised as RPCError exceptions.

However in asynchronous mode, operations return immediately with an RPC object. Error handling and checking for whether a reply has been received must be dealt with manually. See the RPC documentation for details.

Note that in case of the get and get-config operations, the reply is an instance of GetReply which exposes the additional attributes data (as Element) and data_xml (as string), which are of primary interest in case of these operations.

Presence of capabilities is verified to the extent possible, and you can expect a MissingCapabilityError if something is amiss. In case of transport-layer errors, e.g. unexpected session close, TransportError will be raised.

class ncclient.manager.Manager

For details on the expected behavior of the operations and their parameters refer to RFC 4741.

Manager instances are also context managers so you can use it like this:

with manager.connect("host") as m:
    # do your stuff

... or like this:

m = manager.connect("host")
try:
    # do your stuff
finally:
    m.close()
get_config(source[, filter=None])

Retrieve all or part of a specified configuration.

Parameters:
  • source (string) – name of the configuration datastore being queried
  • filter (Filter parameters) – portions of the device configuration to retrieve (by default entire configuration is retrieved)
edit_config(target, config[, default_operation=None, test_option=None, error_option=None])

Loads all or part of a specified configuration to the specified target configuration.

The "rollback-on-error" error_option depends on the :rollback-on-error capability.

Parameters:
  • target (string) – name of the configuration datastore being edited
  • config (string or Element) – configuration (must be rooted in <config> .. </config>)
  • default_operation (string) – one of { "merge", "replace", or "none" }
  • test_option (string) – one of { "test_then_set", "set" }
  • error_option (string) – one of { "stop-on-error", "continue-on-error", "rollback-on-error" }
copy_config(source, target)

Create or replace an entire configuration datastore with the contents of another complete configuration datastore.

Parameters:
  • source (Source and target parameters) – configuration datastore to use as the source of the copy operation or <config> element containing the configuration subtree to copy
  • target (Source and target parameters) – configuration datastore to use as the destination of the copy operation
delete_config(target)

Delete a configuration datastore.

Parameter:target – name or URL of configuration datastore to delete
Type:Source and target parameters
lock(target)

Allows the client to lock the configuration system of a device.

Parameter:target (string) – name of the configuration datastore to lock
unlock(target)

Release a configuration lock, previously obtained with the lock() operation.

Parameter:target (string) – name of the configuration datastore to unlock
locked(target)

Returns a context manager for a lock on a datastore, e.g.:

with m.locked("running"):
    # do your stuff

... instead of:

m.lock("running")
try:
    # do your stuff
finally:
    m.unlock("running")
Parameter:target (string) – name of configuration datastore to lock
Return type:LockContext
get([filter=None])

Retrieve running configuration and device state information.

Parameter:filter (Filter parameters) – portions of the device configuration to retrieve (by default entire configuration is retrieved)
close_session()
Request graceful termination of the NETCONF session, and also close the transport.
kill_session(session_id)

Force the termination of a NETCONF session (not the current one!).

Parameter:session_id (string) – session identifier of the NETCONF session to be terminated
commit([confirmed=False, timeout=None])

Commit the candidate configuration as the device’s new current configuration. Depends on the :candidate capability.

A confirmed commit (i.e. if confirmed is True) is reverted if there is no followup commit within the timeout interval. If no timeout is specified the confirm timeout defaults to 600 seconds (10 minutes). A confirming commit may have the confirmed parameter but this is not required. Depends on the :confirmed-commit capability.

Parameters:
  • confirmed (bool) – whether this is a confirmed commit
  • timeout (int) – confirm timeout in seconds
discard_changes()
Revert the candidate configuration to the currently running configuration. Any uncommitted changes are discarded.
validate(source)

Validate the contents of the specified configuration.

Parameter:source (Source and target parameters) – name of the configuration datastore being validated or <config> element containing the configuration subtree to be validated
async_mode
Specify whether operations are executed asynchronously (True) or synchronously (False) (the default).
raise_mode

Specify which errors are raised as RPCError exceptions. Valid values:

  • "all" – any kind of rpc-error (error or warning)
  • "errors" – where the error-type element says it is an error
  • "none" – neither
client_capabilities
Capabilities object representing the client’s capabilities.
server_capabilities
Capabilities object representing the server’s capabilities.
session_id
session-id assigned by the NETCONF server.
connected
Bolean value indicating whether currently connected to the NETCONF server.

Special kinds of parameters

Some parameters can take on different types to keep the interface simple.

Source and target parameters

Where an method takes a source or target argument, usually a datastore name or URL is expected. The latter depends on the :url capability and on whether the specific URL scheme is supported. Either must be specified as a string. For example, "running", "ftp://user:pass@host/config".

If the source may be a <config> element, e.g. as allowed for the validate RPC, it can also be specified as an XML string or an Element object.

Filter parameters

Where a method takes a filter argument, it can take on the following types:

  • A tuple of (type, criteria).

    Here type has to be one of "xpath" or "subtree".

    • For "xpath" the criteria should be a string containing the XPath expression.
    • For "subtree" the criteria should be an XML string or an Element object containing the criteria.
  • A <filter> element as an XML string or an Element object.

Table Of Contents

Previous topic

Welcome

Next topic

Complete API documentation

This Page