manager – High-level API

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

Customizing

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

ncclient.manager.OPERATIONS = {'cancel_commit': <class 'ncclient.operations.edit.CancelCommit'>, 'close_session': <class 'ncclient.operations.session.CloseSession'>, 'commit': <class 'ncclient.operations.edit.Commit'>, 'copy_config': <class 'ncclient.operations.edit.CopyConfig'>, 'create_subscription': <class 'ncclient.operations.subscribe.CreateSubscription'>, 'delete_config': <class 'ncclient.operations.edit.DeleteConfig'>, 'discard_changes': <class 'ncclient.operations.edit.DiscardChanges'>, 'dispatch': <class 'ncclient.operations.retrieve.Dispatch'>, 'edit_config': <class 'ncclient.operations.edit.EditConfig'>, 'get': <class 'ncclient.operations.retrieve.Get'>, 'get_config': <class 'ncclient.operations.retrieve.GetConfig'>, 'get_schema': <class 'ncclient.operations.retrieve.GetSchema'>, 'kill_session': <class 'ncclient.operations.session.KillSession'>, 'lock': <class 'ncclient.operations.lock.Lock'>, 'poweroff_machine': <class 'ncclient.operations.flowmon.PoweroffMachine'>, 'reboot_machine': <class 'ncclient.operations.flowmon.RebootMachine'>, 'rpc': <class 'ncclient.operations.rpc.GenericRPC'>, 'unlock': <class 'ncclient.operations.lock.Unlock'>, 'validate': <class 'ncclient.operations.edit.Validate'>}

Dictionary of base 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.

Factory functions

A Manager instance is created using a factory function.

ncclient.manager.connect_ssh(*args, **kwds)

Initialize a Manager over the SSH transport. For documentation of arguments see ncclient.transport.SSHSession.connect().

The underlying ncclient.transport.SSHSession is created with CAPABILITIES. It is first instructed to load_known_hosts() and then all the provided arguments are passed directly to its implementation of connect().

To customize the Manager, add a manager_params dictionary in connection parameters (e.g. manager_params={‘timeout’: 60} for a bigger RPC timeout parameter)

To invoke advanced vendor related operation add device_params={‘name’: ‘<vendor_alias>’} in connection parameters. For the time, ‘junos’ and ‘nexus’ are supported for Juniper and Cisco Nexus respectively.

A custom device handler can be provided with device_params={‘handler’:<handler class>} in connection parameters.

ncclient.manager.connect = <function connect>

Manager

Exposes an API for RPC operations as method calls. The return type of these methods depends on whether we are 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 an RPCError exception.

However in asynchronous mode, operations return immediately with the corresponding 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 a 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(session, device_handler, timeout=30)

For details on the expected behavior of the operations and their

parameters refer to RFC 6241.

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_session()

HUGE_TREE_DEFAULT = False

Default for huge_tree support for XML parsing of RPC replies (defaults to False)

get_config(source, filter=None, with_defaults=None)

get_config is mapped to GetConfig

get_schema(identifier, version=None, format=None)

get_schema is mapped to GetSchema

edit_config(config, format='xml', target='candidate', default_operation=None, test_option=None, error_option=None)

edit_config is mapped to EditConfig

copy_config(source, target)

copy_config is mapped to CopyConfig

delete_config(target)

delete_config is mapped to DeleteConfig

dispatch(rpc_command, source=None, filter=None)

dispatch is mapped to Dispatch

lock(target='candidate')

lock is mapped to Lock

unlock(target='candidate')

unlock is mapped to Unlock

get(filter=None, with_defaults=None)

get is mapped to Get

close_session()

close_session is mapped to CloseSession

kill_session(session_id)

kill_session is mapped to KillSession

commit(confirmed=False, timeout=None, persist=None, persist_id=None)

commit is mapped to Commit

cancel_commit(persist_id=None)

cancel_commit is mapped to CancelCommit

discard_changes()

discard_changes is mapped to DiscardChanges

validate(source='candidate')

validate is mapped to Validate

create_subscription(filter=None, stream_name=None, start_time=None, stop_time=None)

create_subscription is mapped to CreateSubscription

reboot_machine()

reboot_machine is mapped to RebootMachine

poweroff_machine()

poweroff_machine is mapped to PoweroffMachine

locked(target)

Returns a context manager for a lock on a datastore, where target is the name of the configuration datastore to lock, e.g.:

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

… instead of:

m.lock("running")
try:
    # do your stuff
finally:
    m.unlock("running")

take_notification(block=True, timeout=None)

Attempt to retrieve one notification from the queue of received notifications.

If block is True, the call will wait until a notification is received.

If timeout is a number greater than 0, the call will wait that many seconds to receive a notification before timing out.

If there is no notification available when block is False or when the timeout has elapse, None will be returned.

Otherwise a Notification object will be returned.

async_mode

Specify whether operations are executed asynchronously (True) or synchronously (False) (the default).

timeout

Specify the timeout for synchronous RPC requests.

raise_mode

Specify which errors are raised as RPCError exceptions. Valid values are the constants defined in RaiseMode. The default value is ALL.

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

Whether currently connected to the NETCONF server.

huge_tree

Whether huge_tree support for XML parsing of RPC replies is enabled (default=False) The default value is configurable through HUGE_TREE_DEFAULT

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 or a tuple containing a dict of namespace mapping and the XPath expression.

  • For “subtree” the criteria should be an XML string or an Element object containing the criteria.

• A list of spec

  Here type has to be “subtree”.

  • the spec should be a list containing multiple XML string or multiple Element objects.

• A <filter> element as an XML string or an Element object.